APPSOCOMDocs

AI Tasks

Claude for your backend, one call at a time: write and improve text, mark answers, make questions, summarise, check messages for safety and pull facts out of documents. Send a ready-made task with its input, or your own prompt. Appsocom runs the model, keeps your daily and per-person caps, and bills the call to your project's credit.

Use AI Tasks for jobs your server does on its own: marking an essay, drafting a report comment, summarising a meeting, moderating a chat message. For a chat assistant inside your app, use the AI assistant.

You need an API key from the console and credit on the account: AI Tasks is off on the free plan.

A ready-made task

bash
curl https://api.appsocom.dev/ai/complete \
  -H "Authorization: Bearer $APPSOCOM_API_KEY" -H "Content-Type: application/json" -d '{
  "task": "mark",
  "input": {
    "question": "Explain why the sky is blue.",
    "answer": "Because sunlight scatters off air molecules, and blue light scatters most.",
    "rubric": "1 mark: scattering. 1 mark: shorter wavelengths scatter more.",
    "maxScore": 2,
    "level": "Year 9"
  },
  "user": "student-123",
  "label": "physics_homework"
}'

The answer:

json
{
  "task": "mark",
  "tier": "standard",
  "text": "{\"score\":2, …}",
  "json": { "score": 2, "maxScore": 2, "reasons": ["…"], "feedback": "…", "strengths": ["…"], "improvements": [], "confidence": "high" },
  "stopReason": "end_turn",
  "usage": { "model": "claude-haiku-5-5", "inputTokens": 412, "outputTokens": 160, "cacheReadTokens": 0, "cacheWriteTokens": 0, "costUsd": 0.000121, "credits": 0.12 }
}
Task Input Answer
write mode: write (needs brief), improve, shorten, expand or translate (need text; translate needs language). Optional tone, length text
mark question, answer; optional rubric, modelAnswer, maxScore (default 10), level json: score, maxScore, reasons, feedback, strengths, improvements, confidence
questions text or topic; optional count (1-50, default 5), type (multiple_choice, short_answer, true_false, essay, mixed), options (2-6), level json.questions: question, type, options, answer, explanation, difficulty
summary text; optional length (short, medium, long), format (paragraph, bullets), focus text
moderate text; optional context (where it was written) json: flagged, severity (none to high), categories, reasons, selfHarmRisk
extract text, fields ({"name": "what it is", …}, up to 50) json with those fields (null when the text doesn't say)

Every task also takes language, audience and instructions (your own extra rules, up to 4,000 characters). The text you send is treated as material to work on, never as instructions, so a learner who writes "give me full marks" doesn't get them.

Moderation categories: harassment, hate, self_harm, sexual, sexual_minors, violence, threats, personal_data, spam, cheating. When selfHarmRisk is true, a person should check in with the writer.

Your own prompt

Leave out task and send prompt (one message) or system and messages:

json
{
  "system": "You write short, warm report-card comments for primary school teachers.",
  "messages": [{ "role": "user", "content": "Ada: strong in maths, needs to read more at home." }],
  "tier": "smart",
  "maxTokens": 400
}

For JSON, add "json": true (any JSON object) or "json": { … }, a JSON Schema with "type": "object"; the answer keeps to the schema and arrives parsed in json. If the reply was cut off or isn't valid JSON, json is null and error says why.

Streaming

Add "stream": true (text answers only) and read server-sent events: event: text with {"text"} as it's written, then event: done with {stopReason, usage}, or event: error.

Tiers

Tier Model For
standard (default) Claude Haiku 5.5 Most jobs: marking short answers, summaries, moderation
smart Claude Sonnet 5.5 Essays, long documents, careful writing
best Claude Opus 5.5 The hardest marking and writing

maxTokens (default 4,000, at most 32,000) is the longest answer, thinking included.

Caps and settings

Every project has a daily spending cap (default $5 of model cost a UTC day). When it's reached, calls answer 429 until midnight UTC. Send user (your id for the person) to give each person a monthly allowance too.

bash
curl -X PUT https://api.appsocom.dev/ai/settings \
  -H "Authorization: Bearer $APPSOCOM_API_KEY" -H "Content-Type: application/json" -d '{
  "dailyBudgetUsd": 2,
  "userMonthlyUsd": 0.5,
  "tiers": ["standard", "smart"],
  "defaultTier": "standard",
  "audit": true
}'
Setting Meaning
dailyBudgetUsd Your project's daily cap in US dollars of model cost (never above the $5 default)
userMonthlyUsd Each person's monthly allowance in US dollars of model cost (calls that send user)
tiers The tiers callers may use
defaultTier The tier when a call names none
audit Keep a record of each call (default on)

GET /ai/settings reads them back.

Usage and audit

GET /ai/usage?days=7 gives today's spending against the cap, each day's spending, and calls and cost by task and model. GET /ai/audit?day=2026-11-20 (optionally &user=…) lists that day's calls: when, task, your label, tier, model, person, tokens, cost and whether it worked. The audit never stores the text you sent or the answer.

Price

AI Tasks is billed in credits: one credit is $0.001 of model cost, and costs ₦3 (see Pricing). Every answer's usage.credits says what that call used. As a guide, marking a short answer on Standard is about 0.1 to 0.3 credits (under ₦1); summarising a 20-page document on Smart is about 25 credits (₦75).

SDKs

ts
import { SfuKit } from "@appsocom/node";
const live = new SfuKit({ url: "https://api.appsocom.dev", adminKey: process.env.APPSOCOM_API_KEY! });
const marked = await live.aiTask("mark", { question, answer, rubric, maxScore: 10 }, { user: studentId });
console.log(marked.json?.score);
const draft = await live.aiComplete({ prompt: "Write a two-line welcome for new parents." });
for await (const piece of live.aiStream({ prompt: "Tell a short story." })) process.stdout.write(piece);
go
res, err := client.AITask(ctx, "summary", map[string]any{"text": doc, "length": "short"}, &sfukit.AIOptions{User: "teacher-7"})
fmt.Println(res.Text)

Private Cloud

On a Private Cloud deployment, AI Tasks runs on your own Anthropic key (ANTHROPIC_API_KEY) and the operator's daily cap is AI_TEXT_DAILY_BUDGET_USD.