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
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:
{
"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:
{
"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.
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
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);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.