Vife API · Docs
Vife API documentation
A model API returns text. The Vife API takes a task and returns finished work: documents, slides, spreadsheets, images, video and audio as files, made by the same agent that runs vife.ai. One key works over REST, MCP and the command line.
- Base URL
- https://api.vife.ai
- Auth
- Authorization: Bearer vife_sk_…
- API version
- 2026-11-11
- MCP
- https://api.vife.ai/v1/mcp
On this page
Get started
Core
Events
Tools for agents
Reference
Get started
Make your first call#
Three steps: create a key, send a task, read the result. The call returns at once with status queued; the agent then plans, researches and builds while you poll or wait for a webhook.
- Create a key in Vife › Settings › Developer (open it) and export it:
export VIFE_API_KEY=vife_sk_…. The secret is shown once. - Create a task with
POST /v1/tasks. Send anIdempotency-Keyso a retry never starts a second task. - Read
GET /v1/tasks/{task_id}untilstatusiscompleted.result.textholds the answer andresult.artifactsthe files.
curl -X POST https://api.vife.ai/v1/tasks \
-H "Authorization: Bearer $VIFE_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: first-task-001" \
-d '{
"input": "Write a one-page brief on the history of lighthouses, as a PDF.",
"mode": "document"
}'
# Then read it until status is completed (or use a webhook):
curl https://api.vife.ai/v1/tasks/$TASK_ID -H "Authorization: Bearer $VIFE_API_KEY"// Node 22 or later: save as first-task.mjs, run with `node first-task.mjs`
const API = "https://api.vife.ai";
const headers = { Authorization: `Bearer ${process.env.VIFE_API_KEY}` };
const response = await fetch(`${API}/v1/tasks`, {
method: "POST",
headers: { ...headers, "Content-Type": "application/json", "Idempotency-Key": "first-task-001" },
body: JSON.stringify({ input: "Write a one-page brief on the history of lighthouses, as a PDF.", mode: "document" }),
});
let task = await response.json();
if (!response.ok) throw new Error(`${task.error.code}: ${task.error.message}`);
// A task runs for minutes: poll every 5 seconds (or subscribe to task.completed).
while (task.status === "queued" || task.status === "running") {
await new Promise((resolve) => setTimeout(resolve, 5000));
task = await (await fetch(`${API}/v1/tasks/${task.id}`, { headers })).json();
}
console.log(task.status, task.result?.text);
for (const file of task.result?.artifacts ?? []) console.log(file.name, file.url);# pip install requests
import os, time, requests
API = "https://api.vife.ai"
headers = {"Authorization": f"Bearer {os.environ['VIFE_API_KEY']}"}
response = requests.post(
f"{API}/v1/tasks",
headers={**headers, "Idempotency-Key": "first-task-001"},
json={"input": "Write a one-page brief on the history of lighthouses, as a PDF.", "mode": "document"},
timeout=30,
)
task = response.json()
if not response.ok:
raise RuntimeError(f"{task['error']['code']}: {task['error']['message']}")
# A task runs for minutes: poll every 5 seconds (or subscribe to task.completed).
while task["status"] in ("queued", "running"):
time.sleep(5)
task = requests.get(f"{API}/v1/tasks/{task['id']}", headers=headers, timeout=30).json()
result = task["result"] or {}
print(task["status"], result.get("text"))
for file in result.get("artifacts", []):
print(file["name"], file["url"]){
"object": "task",
"id": "4f9d2c1e-8b7a-4c3d-9e2f-1a0b9c8d7e6f",
"title": "History of lighthouses brief",
"mode": "document",
"status": "queued",
"source": "api",
"project_id": null,
"computer": {
"kind": "cloud"
},
"created_at": "2026-11-13T09:30:00.000Z",
"updated_at": "2026-11-13T09:30:00.000Z",
"metadata": {},
"queued_messages": 0,
"result": null,
"error": null,
"pending_input": null,
"credits_used": 0,
"web_url": "https://vife.ai/agent/4f9d2c1e-8b7a-4c3d-9e2f-1a0b9c8d7e6f"
}Other ways to start#
- MCPConnect an MCP clientClaude Code, Cursor or any client that speaks Streamable HTTP: every operation is a tool.
- CLIUse the vife commandOne command per operation, plus wait, upload and download helpers.
- AgentsSet up with an agentPaste one prompt into your coding agent and let it read the spec and connect.
Common tasks#
- slideGenerate a slide deck
mode: slidewith a brief and attached files. - webhookGet told when a task finishesSubscribe to
task.completedand verify the signature. - scheduleRun a weekly research reportAn automation with a timer trigger.
- filesGive a task your filesUpload, then pass
file_ids. - imageGenerate an image
mode: imagewith a model from the catalog. - mcpUse Vife from Claude CodeOne
claude mcp addcommand.
Get started
Authentication#
Every request carries an API key in the Authorization header. Keys belong to your Vife account: a task a key starts is your task, billed to your credits and visible in the web app.
- Create, rename, rotate and revoke keys in Settings › Developer; an account holds up to 10 active keys. The secret (
vife_sk_…) is shown once. - A key is
full(reads and writes) orread_only(reads only; a write answers 403read_only_key). - Send the key only as
Authorization: Bearer vife_sk_….x-api-keyheaders and?api_key=query strings are refused. - Admin keys (
vife_admin_sk_…) are refused on user operations with 403admin_key_not_allowed.
curl https://api.vife.ai/v1/me -H "Authorization: Bearer $VIFE_API_KEY"{
"object": "api_key_identity",
"owner": {
"kind": "user",
"user_id": "0b6f…",
"email": "you@example.com"
},
"key": {
"id": "8c1d…",
"name": "Reporting job",
"prefix": "vife_sk_3kq9xz",
"last4": "f2a7",
"access": "full",
"expires_at": null,
"created_at": "2026-11-12T15:04:00.000Z"
}
}| Status | Code | Meaning |
|---|---|---|
| 401 | missing_api_key | No Authorization: Bearer header. |
| 401 | invalid_api_key | The key does not exist. |
| 401 | api_key_revoked · api_key_expired | The key was revoked or passed its expiry. |
| 401 | account_unavailable | The account is suspended or being deleted. |
| 403 | read_only_key | A read-only key called a write operation. |
| 403 | admin_key_not_allowed | An admin key called a user operation. |
Core
Tasks#
A task is one agent run, exactly like one started in the web app: same modes, options, queue and credits. It runs for seconds to many minutes, so the create call returns at once and you follow the task to the end.
- POST
/Create a taskv1/ tasks - GET
/List tasks (filter by status, source, mode, project, query, dates)v1/ tasks - GET
/Get a task: status, result, error, pending inputv1/ tasks/ {task_id} - POST
/Answer a question or send a follow-upv1/ tasks/ {task_id}/ messages - GET
/Read the transcriptv1/ tasks/ {task_id}/ messages - POST
/Stop the runv1/ tasks/ {task_id}/ stop - POST
/Make the task public;v1/ tasks/ {task_id}/ share DELETEmakes it private
Create a task#
curl -X POST https://api.vife.ai/v1/tasks \
-H "Authorization: Bearer $VIFE_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: launch-deck-2026-q3" \
-d '{
"input": "Build a 10-slide launch deck for our Q3 product update from the attached brief.",
"mode": "slide",
"file_ids": ["$FILE_ID"],
"timezone": "Europe/Berlin",
"metadata": {"order_id": "A-1042"}
}'| Field | Type | Description |
|---|---|---|
input | string, required | What the task should do, or your answer to its question. Up to 200,000 characters. |
mode | string | One of the eight modes below; agent by default. |
options | object | The composer's options, as the web app sends them (for example options.image.selectedModel). |
agent_tier | string | lite, pro or max (max needs a paid plan). Not for chat. |
capabilities | object | Skills and connectors for this message, as the composer sends them. Not for chat. |
file_ids | string[] | Up to 10 ids of files in your account (see Files). |
timezone | string | Your IANA time zone, such as Europe/Berlin; the agent reads dates in it. Not for chat. |
project_id | string | Put the task in one of your projects. |
metadata | object | Up to 20 string values (keys [A-Za-z0-9_.-], 1-40 characters; values up to 500). Returned on every read and event. |
| Mode | What it does |
|---|---|
agent | The default. The full agent plans, researches, browses, uses your skills and connectors, and writes files. |
chat | A plain conversation with one text model (options.chat.selectedModel): no tools and no queue. |
document | The web app's Document mode: the agent writes a document. |
slide | The Slides mode: the agent builds a slide deck. |
spreadsheet | The Spreadsheet mode: the agent builds a spreadsheet. |
image · video · audio | Generates media through background jobs; see Images, video, audio. |
Unknown fields answer 400 unknown_parameter, so a typo never passes silently.
Lifecycle#
Follow it with webhooks (the events shown) or by polling GET /v1/tasks/{task_id}. A message to a finished or stopped task starts a new turn.
| Status | Meaning | What to do |
|---|---|---|
queued | Accepted, not running yet (or a follow-up waits). | Keep polling or wait for a webhook. |
running | The agent is working. | Keep polling or wait for a webhook. |
needs_input | The task waits for you; pending_input says for what. | Answer with a message, or act at web_url. |
completed | Done. result.text and result.artifacts are set. | Download the files; send a follow-up to continue. |
failed | error.code and error.message say why, for example insufficient_credits. | Fix the cause and send a new message. |
stopped | Stopped by you or in the web app. | Send a message to start a new turn. |
Wait for the result#
Poll GET /v1/tasks/{task_id} every few seconds, or subscribe a webhook to task.completed, task.failed and task.needs_input and skip polling. Each artifact's url downloads the file; GET /v1/tasks/{task_id}/files lists every file the task made.
curl https://api.vife.ai/v1/tasks/$TASK_ID -H "Authorization: Bearer $VIFE_API_KEY"{
"object": "task",
"id": "4f9d2c1e-8b7a-4c3d-9e2f-1a0b9c8d7e6f",
"title": "Q3 launch deck",
"mode": "slide",
"status": "completed",
"source": "api",
"project_id": null,
"computer": {
"kind": "cloud"
},
"created_at": "2026-11-13T09:30:00.000Z",
"updated_at": "2026-11-13T09:41:12.000Z",
"metadata": {
"order_id": "A-1042"
},
"queued_messages": 0,
"result": {
"text": "Your 10-slide launch deck is ready.",
"text_truncated": false,
"artifacts": [
{
"object": "file",
"id": "9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d",
"name": "q3-launch-deck.pptx",
"type": "document",
"mime_type": "application/vnd.openxmlformats-officedocument.presentationml.presentation",
"size_bytes": 2841193,
"url": "https://file.vife.ai/4f9d2c1e-8b7a-4c3d-9e2f-1a0b9c8d7e6f/outputs/q3-launch-deck.pptx",
"thumbnail_url": null,
"created_at": "2026-11-13T09:41:10.000Z"
}
],
"artifacts_truncated": false
},
"error": null,
"pending_input": null,
"credits_used": 42,
"web_url": "https://vife.ai/agent/4f9d2c1e-8b7a-4c3d-9e2f-1a0b9c8d7e6f"
}Answer or continue#
When status is needs_input, pending_input says what the task waits for. A question is answered with a message: one of choices, an option's response, or your own words. An action (an authorization, a connector or a confirmation) is answered in the web app at the task's web_url. A message to a finished task continues it; a message to a running task is queued and runs next (delivery: queued).
curl -X POST https://api.vife.ai/v1/tasks/$TASK_ID/messages \
-H "Authorization: Bearer $VIFE_API_KEY" \
-H "Content-Type: application/json" \
-d '{"input": "Now turn it into a one-page PDF summary."}'{
"object": "task_message_receipt",
"delivery": "started",
"task": {
"object": "task",
"id": "4f9d2c1e-8b7a-4c3d-9e2f-1a0b9c8d7e6f",
"status": "queued"
}
}Stop, share and list#
POST /v1/tasks/{task_id}/stopstops the run and returns the task once it settled; it then readsstoppeduntil a new message starts a new turn.POST /v1/tasks/{task_id}/sharemakes the task public, as the web's Share dialog does, and returns itsurl; anyone with the link can read it.DELETEmakes it private again. A task that holds Google Workspace data is only shared from the web app (403google_user_data).GET /v1/taskslists your tasks from every source (api,web,automation), newest first, withlimit1-100 and acursor.
Read the transcript#
curl "https://api.vife.ai/v1/tasks/$TASK_ID/messages?order=desc&limit=20" -H "Authorization: Bearer $VIFE_API_KEY"{
"object": "task.message",
"id": "1c2d3e4f-5a6b-4c7d-8e9f-0a1b2c3d4e5f",
"role": "assistant",
"type": "tool_call",
"text": null,
"files": [],
"tool": {
"name": "web_search",
"status": "succeeded",
"summary": "Q3 product launches"
},
"created_at": "2026-11-13T09:31:00.000Z"
}Tool steps carry their name, status and a short label only, never their internal payloads.
| Status | Code | When |
|---|---|---|
| 400 | invalid_request · invalid_options · invalid_capabilities · file_not_found | The body or one of its files is not valid. |
| 402 | insufficient_credits | The balance is at or below zero. |
| 403 | task_start_blocked | This account cannot start tasks. |
| 404 | task_not_found · project_not_found | Unknown, deleted or another account's task or project. |
| 409 | chat_generation_active | A chat task is still answering (Retry-After: 5). |
| 429 | concurrency_limit_reached | Your plan's running tasks are all busy (Retry-After: 30). |
| 503 | task_admission_failed · stop_failed | Retry with the same Idempotency-Key. |
Core
Files#
Upload inputs for a task and download every file a task made. Uploads go straight to Vife's file storage in three calls, as in the web app; the bytes never pass through the API.
- POST
/Start an upload: presigned PUT URL(s)v1/ files/ uploads - POST
/Complete the upload; answers the stored filev1/ files/ uploads/ {upload_id}/ complete - GET
/Get a file's detailsv1/ files/ {file_id} - GET
/Download: a redirect to the filev1/ files/ {file_id}/ content - GET
/A task's files, inputs and outputs, newest firstv1/ tasks/ {task_id}/ files
Upload a file#
# 1. Start the upload with the file's name, type and exact size
curl -X POST https://api.vife.ai/v1/files/uploads \
-H "Authorization: Bearer $VIFE_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: upload-brief-001" \
-d '{"name": "brief.pdf", "mime_type": "application/pdf", "size_bytes": 182331}'
# → {"id": ..., "url": ..., "headers": {...}, "upload_token": ..., "expires_at": ...}
# 2. PUT the bytes to url with exactly the returned headers
curl -X PUT "$UPLOAD_URL" \
-H "Content-Type: application/octet-stream" \
--data-binary @brief.pdf
# 3. Complete it before expires_at; the answer is the stored file
curl -X POST https://api.vife.ai/v1/files/uploads/$UPLOAD_ID/complete \
-H "Authorization: Bearer $VIFE_API_KEY" \
-H "Content-Type: application/json" \
-d '{"upload_token": "'"$UPLOAD_TOKEN"'"}'- Attach the file to a task with
"file_ids": ["$UPLOAD_ID"](up to 10 per message). - Files up to 128 MiB are one PUT to
url. Larger files, up to 1 GiB, answerpartsinstead: PUT each 64 MiB byte range to its parturl, keep each response'sETagheader, and complete with"parts": [{"part_number": 1, "etag": "..."}, ...]. - At most 20 uploads (4 large ones) can be in progress per account; one that is never completed stops counting after 2 hours.
Download a file#
curl -L -o deck.pptx https://api.vife.ai/v1/files/$FILE_ID/content -H "Authorization: Bearer $VIFE_API_KEY"The API answers a redirect to the file's storage URL (follow it with -L). GET /v1/files/{file_id} returns the file's name, mime_type, size_bytes, source (upload, generated, workspace or computer), task_id, url and thumbnail_url.
| Status | Code | When |
|---|---|---|
| 400 | file_too_large | Above 1 GiB. |
| 400 | invalid_upload_token · upload_size_mismatch | The token is for another upload or expired, or the bytes do not match size_bytes. |
| 404 | file_not_found | Unknown, deleted, still uploading, or another account's file. |
| 409 | upload_not_received · upload_expired | Complete came before the bytes, or after expires_at. |
| 429 | upload_limit_reached | Too many uploads in progress (Retry-After: 60). |
Core
Images, video and audio#
Media is made by a task in image, video or audio mode, exactly as in the web composer, and charged the same way. Pick a model from the catalog and set planMode: false for a direct one-shot generation.
- GET
/The selectable models, with inputs, parameters and price (v1/ media/ models ?kind=image|video|audio) - GET
/A task's media jobsv1/ tasks/ {task_id}/ media_jobs - GET
/One job, with its files once it succeededv1/ media_jobs/ {job_id} - GET
/Your unfinished jobs across tasksv1/ media_jobs
curl https://api.vife.ai/v1/media/models?kind=image -H "Authorization: Bearer $VIFE_API_KEY"
curl -X POST https://api.vife.ai/v1/tasks \
-H "Authorization: Bearer $VIFE_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: poster-001" \
-d '{"input":"A lighthouse at dusk, flat poster style","mode":"image","options":{"image":{"planMode":false,"selectedModel":"gpt-image-2","size":"1024x1024"}}}'- Plan mode is on by default: without
planMode: falsethe task first proposes a plan and waits for your approval (needs_input). - The task starts background media jobs. A job's
statusgoes fromqueuedthroughsubmitted,runningandfinalizingtosucceeded,failedorcancelled; a succeeded job lists itsfiles. - Subscribe to
media.completedandmedia.failedinstead of polling jobs. A cancelled job sends no event.
Core
Automations#
An automation runs a task on a schedule or a trigger, as on the web's Automations page. Top-level keys are snake_case; triggers and options take the web app's JSON.
- POST
/Create an automationv1/ automations - GET
/List automations, newest firstv1/ automations - PATCH
/Change only the fields you send;v1/ automations/ {automation_id} DELETEremoves it - POST
/Pause;v1/ automations/ {automation_id}/ pause …/resumeresumes - POST
/Run it once now (the web's Test run)v1/ automations/ {automation_id}/ runs - GET
/Its runs (v1/ automations/ {automation_id}/ runs filterall, triggered, failed) - POST
/Rotate a webhook trigger's tokenv1/ automations/ {automation_id}/ webhooks/ {hook_id}/ secret
curl -X POST https://api.vife.ai/v1/automations \
-H "Authorization: Bearer $VIFE_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: competitor-brief" \
-d '{
"kind": "schedule",
"title": "Monday competitor brief",
"instructions": "Research what our five competitors shipped last week and write a one-page brief.",
"triggers": [
{
"kind": "timer",
"frequency": "weekly",
"timezone": "Europe/Berlin",
"hour": 8,
"minute": 0,
"dayOfWeek": 1,
"dayOfMonth": null,
"runAt": null
}
]
}'POST …/runsstarts one run perIdempotency-Key, so a retry never starts a second run. It answers 402insufficient_creditsat a balance at or below zero.- Subscribe to
automation.run.finishedto hear when a run ends:success,failed, ornot_triggeredwhen the agent found nothing to do. Runs that never started send nothing. - For a webhook trigger,
POST …/webhooks/{hook_id}/secretreturns its token once; every call makes a new token. - An automation that targets your Mac runs at
ask_for_approvalor lower when saved with a key (403desktop_approval_not_allowedotherwise).
Core
Skills and connectors#
Switch what new tasks may use, as in Settings › Skills and Settings › Connectors. The API never signs in to a service for you.
- GET
/Your library and the official skills you can addv1/ skills - POST
/Add and turn on;v1/ skills/ {skill_id}/ enable …/disableturns off and keeps it - GET
/Connectors with theirv1/ connectors status(?installed=truefor yours) - POST
/Start new tasks with it;v1/ connectors/ {connector_id}/ enable …/disablestops that
curl -X POST https://api.vife.ai/v1/skills/$SKILL_ID/enable -H "Authorization: Bearer $VIFE_API_KEY"- A Pro skill needs a paid plan (403
skill_pro_required). A Skill Hub skill outside your library is added in the web app first (can_enablesays which ones the API can switch on). - A connector that is
not_connectedorneeds_sign_inis connected at itsconnect_urlin the web app; enabling it before that answers 409connector_needs_sign_inorconnector_not_installed.
Core
Account and credits#
API tasks spend your account's ordinary Vife credits. There is no separate API price: a task costs what it would cost in the web app.
- GET
/Credit balance, plan and the key's rate limitsv1/ account - GET
/Your credit history, newest first (v1/ account/ transactions ?type=)
curl https://api.vife.ai/v1/account -H "Authorization: Bearer $VIFE_API_KEY"| Field | Contains |
|---|---|
credits | balance, total_earned, total_spent, low_threshold |
plan | code (basic for a free account), name, status, billing_cycle, current_period_end, auto_renew, concurrent_tasks, monthly_credits, pass |
rate_limits | tier, key_per_minute, account_per_minute |
Subscribe to credits.low to hear when the balance falls below 50 credits (once per fall; it fires again after the balance went back up). A balance at or below zero refuses new turns with 402 insufficient_credits. Buying credits and changing the plan stay in the web app: see plans and credits.
Events
Webhooks#
Signed HTTPS events when work finishes, fails or needs you. Add an endpoint in Settings › Developer › Webhooks, pick its events, and keep the whsec_ secret. Events fire for every task of your account, whatever started it; data.task.source says whether it was the API, the web app or an automation.
| Event | Sent when | data |
|---|---|---|
task.completed | A task's run finished with a result. | {task} |
task.failed | A task's run failed; task.error says why. | {task} |
task.needs_input | A task waits for an answer or an action. | {task} |
media.completed | A media job succeeded; up to 20 files. | {media_job} |
media.failed | A media job failed (a cancelled job sends nothing). | {media_job} |
automation.run.finished | An automation run ended: success, failed or not_triggered. | {automation_run, automation} |
credits.low | The balance fell below the low-credit threshold. | {balance, threshold, transaction} |
Payload and headers#
Content-Type: application/json; charset=utf-8
Vife-Signature: t=1794562873,v1=5f8a…
Vife-Event-Id: b3e1f0c2-7d4a-4e9b-a6c5-2f8d1e0b9a73
Vife-Event-Type: task.completed
Vife-Delivery-Id: …
Vife-Delivery-Attempt: 1{
"id": "b3e1f0c2-7d4a-4e9b-a6c5-2f8d1e0b9a73",
"type": "task.completed",
"created_at": "2026-11-13T09:41:13.000Z",
"api_version": "2026-11-11",
"data": {
"task": {
"object": "task",
"id": "4f9d2c1e-8b7a-4c3d-9e2f-1a0b9c8d7e6f",
"title": "Q3 launch deck",
"mode": "slide",
"status": "completed",
"source": "api",
"project_id": null,
"computer": {
"kind": "cloud"
},
"created_at": "2026-11-13T09:30:00.000Z",
"updated_at": "2026-11-13T09:41:12.000Z",
"metadata": {
"order_id": "A-1042"
},
"queued_messages": 0,
"result": {
"text": "Your 10-slide launch deck is ready.",
"text_truncated": false,
"artifacts": [
{
"object": "file",
"id": "9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d",
"name": "q3-launch-deck.pptx",
"type": "document",
"mime_type": "application/vnd.openxmlformats-officedocument.presentationml.presentation",
"size_bytes": 2841193,
"url": "https://file.vife.ai/4f9d2c1e-8b7a-4c3d-9e2f-1a0b9c8d7e6f/outputs/q3-launch-deck.pptx",
"thumbnail_url": null,
"created_at": "2026-11-13T09:41:10.000Z"
}
],
"artifacts_truncated": false
},
"error": null,
"pending_input": null,
"credits_used": 42,
"web_url": "https://vife.ai/agent/4f9d2c1e-8b7a-4c3d-9e2f-1a0b9c8d7e6f"
}
}
}Verify the signature#
Vife-Signature: t=<unix seconds>,v1=<hex> is an HMAC-SHA256 of t + "." + raw body keyed by your endpoint secret. Verify against the raw bytes before parsing JSON. Refuse a timestamp more than 300 seconds away, and accept any matching v1: there are two while a secret rotates (24 hours).
const crypto = require("node:crypto");
// header: the Vife-Signature value; body: the raw request body (a string);
// secrets: your endpoint's whsec_ secret (two during a 24 h rotation).
function verifyVifeSignature(header, body, secrets, nowSeconds = Math.floor(Date.now() / 1000)) {
const parts = header.split(",").map((part) => part.trim().split("="));
const timestamp = Number(parts.find(([key]) => key === "t")?.[1]);
const received = parts.filter(([key]) => key === "v1").map(([, value]) => value);
if (!Number.isInteger(timestamp) || Math.abs(nowSeconds - timestamp) > 300) return false;
return secrets.some((secret) => {
const expected = crypto.createHmac("sha256", secret).update(timestamp + "." + body, "utf8").digest("hex");
return received.some((value) => value.length === expected.length &&
crypto.timingSafeEqual(Buffer.from(value), Buffer.from(expected)));
});
}import hashlib, hmac, time
def verify_vife_signature(header: str, body: bytes, secrets: list[str]) -> bool:
parts = [part.strip().split("=", 1) for part in header.split(",")]
timestamps = [value for key, value in parts if key == "t"]
received = [value for key, value in parts if key == "v1"]
if not timestamps or not timestamps[0].isdigit():
return False
timestamp = int(timestamps[0])
if abs(time.time() - timestamp) > 300:
return False
signed = str(timestamp).encode() + b"." + body
for secret in secrets:
expected = hmac.new(secret.encode(), signed, hashlib.sha256).hexdigest()
if any(hmac.compare_digest(value, expected) for value in received):
return True
return FalseDelivery and retries#
- Answer 2xx within 10 seconds. Do slow work after you answer.
- Delivery is at least once: deduplicate by
Vife-Event-Id. - A failed delivery is retried 10 times over about 40 hours, after 30 s, 2 min, 10 min, 30 min, 1 h, 2 h, 4 h, 8 h, 12 h and 12 h. An endpoint that fails ten times in a row over a day is turned off, and you are told.
- Settings › Developer › Deliveries is the delivery log: every attempt with its status, and a resend button. A test event checks a new endpoint.
Tools for agents
MCP server#
Every API operation is an MCP tool. Connect any MCP client to one URL with the same key: your key decides which tools exist, and a read-only key cannot change anything.
| URL | https://api.vife.ai/v1/mcp |
| Transport | Streamable HTTP, JSON responses, stateless (no session id) |
| Auth | Authorization: Bearer vife_sk_…; the same rate limits and credits as HTTP calls |
| Tools | One per operation, named by its operationId (createTask, getTask, …); see Operations |
Connect your client#
claude mcp add --transport http vife https://api.vife.ai/v1/mcp \
--header "Authorization: Bearer $VIFE_API_KEY"{
"mcpServers": {
"vife": {
"url": "https://api.vife.ai/v1/mcp",
"headers": {
"Authorization": "Bearer ${env:VIFE_API_KEY}"
}
}
}
}URL: https://api.vife.ai/v1/mcp
Type: Streamable HTTP (remote)
Header: Authorization: Bearer <your vife_sk_ key>Claude Code expands $VIFE_API_KEY from your shell when you run the command. For Cursor, put the JSON in .cursor/mcp.json in a project, or in ~/.cursor/mcp.json for every project; Cursor resolves ${env:VIFE_API_KEY} from its environment.
Inside Vife, Settings › Connectors › Vife API connects the Vife agent and automations to this server with a key you paste. It starts off and is turned on per task, project or automation that needs it.
Set up with an agent#
Paste this into Claude Code, Cursor or another coding agent. It reads the spec, connects the server and checks the tools, with the key kept in the environment.
Read https://vife.ai/developers/docs and https://api.vife.ai/v1/openapi.json, then connect the Vife MCP server at https://api.vife.ai/v1/mcp (Streamable HTTP) with the header "Authorization: Bearer $VIFE_API_KEY". The key is in the VIFE_API_KEY environment variable; never print it or write it into a file I commit. When it is connected, list the Vife tools you can call.How tools behave#
tools/listlists only what the key may call: a user key gets the user operations, a read-only key only the reads.- A tool's input joins the operation's path, query and body fields. Tools that create something take an optional
idempotency_keyargument: pass the same value when a call is retried so it runs once. AnIdempotency-Keyheader on the MCP request is ignored. - A tool call runs as the operation's own
/v1request. A non-2xx answer becomes a tool result withisErrorand the/v1error object; a missing or invalid key stays HTTP 401. - Uploads stay two-step (the upload tool returns the presigned URLs), downloads return the file's location, and long-running work returns an id you read again with the matching get tool.
Tools for agents
CLI#
vife is the API from a terminal: one command per operation, generated from the same OpenAPI document, plus helpers that wait for a task and move files. It reads the key from VIFE_API_KEY or vife auth login; --json prints the API's JSON only. It needs Node.js 22 or later.
npm install -g @vifeai/clivife auth login # reads the key from stdin; never printed
vife tasks create --mode slide --input "Turn this spec into a 12-slide deck" \
--idempotency-key spec-deck-001
vife tasks wait $TASK_ID # polls until done; exit codes below
vife files upload ./brief.pdf # the three upload calls in one
vife files download $FILE_ID --output deck.pptx
vife webhooks verify --signature "$SIGNATURE" --body-file event.json
vife call listMediaModels --kind image # any operation by its operationId| Code | Meaning |
|---|---|
| 0 | OK |
| 1 | Refused by the API |
| 2 | Usage error |
| 3 | Key missing or refused |
| 4 | Rate limited |
| 5 | Unreachable or server error |
| 6 · 7 · 8 | tasks wait: failed or stopped · timed out · needs input |
Reference
Errors#
Every error has the same shape and an X-Request-Id header. Branch on code, which is stable; message is English text for people. Quote request_id when you contact support.
{
"error": {
"type": "invalid_request_error",
"code": "unknown_parameter",
"message": "Unknown parameter tittle.",
"request_id": "6a1f0e2d-3c4b-4a59-8e7d-9f0a1b2c3d4e",
"param": "tittle"
}
}| Status | type | Common codes |
|---|---|---|
| 400 | invalid_request_error | invalid_request, unknown_parameter, file_not_found, invalid_idempotency_key |
| 401 | authentication_error | missing_api_key, invalid_api_key, api_key_revoked, api_key_expired |
| 402 | billing_error | insufficient_credits |
| 403 | permission_error | read_only_key, admin_key_not_allowed, skill_pro_required |
| 404 | not_found_error | task_not_found, file_not_found, route_not_found |
| 409 | conflict_error | chat_generation_active, upload_not_received, idempotency_request_in_progress |
| 422 | idempotency_error | idempotency_key_reused |
| 429 | rate_limit_error | rate_limited, concurrency_limit_reached, upload_limit_reached |
| 500 · 503 | api_error | internal_error, task_admission_failed, rate_limiter_unavailable |
Retry a 429 or 503 after its Retry-After header, with the same Idempotency-Key. A 500 never carries the cause; retry once, then contact support with the request_id.
Reference
Limits#
Requests are counted per key and per account each minute. Every answer carries X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset; a 429 rate_limited adds Retry-After. GET /v1/account returns the limits of the calling key.
| Plan | Per key | Per account, all keys |
|---|---|---|
| Free | 30 | 60 |
| Paid plan | 120 | 300 |
- Running tasks count against your plan's concurrency limit (
plan.concurrent_tasks); a task beyond it answers 429concurrency_limit_reachedwithRetry-After: 30. - Per client address: 1,200 requests a minute before the key is checked, 60 failed authentications a minute, and 60 reads a minute of the OpenAPI document.
Idempotency#
- Send
Idempotency-Key(1-255 visible ASCII characters) on a POST. A repeat with the same request replays the stored answer withIdempotent-Replayed: true; keys are kept 24 hours per API key. - The same key with a different request answers 422
idempotency_key_reused; while the first request still runs, 409idempotency_request_in_progress. - A 5xx, 429 or 402 answer, or a 409 with
Retry-After, is not stored, so a retry with the same key runs again once the cause clears.
Sizes#
| What | Limit |
|---|---|
| File | 1 GiB (one PUT up to 128 MiB, then 64 MiB parts) |
| Uploads in progress | 20 per account, 4 of them large |
| Files per message | 10 file_ids |
| Task input | 200,000 characters |
| Metadata | 20 string values, up to 500 characters each, 4 KB in all |
| List pages | limit 1-100, 20 by default |
| Event text | result.text up to 4,000 characters and 20 artifacts per task event |
| MCP request body | 256 KB |
Reference
Operations#
Every user operation of the API, generated from the live OpenAPI 3.1 document. Each one is also an MCP tool named by its operationId. A read-only key can call the reads only.
38 operations · openapi.json
| Endpoint · operationId | Summary | Access |
|---|---|---|
| Account | ||
GET/getMe | Who am I | read |
GET/getAccount | Get your account | read |
GET/listAccountTransactions | List credit transactions | read |
| Tasks | ||
GET/listTasks | List tasks | read |
POST/createTask | Create a task | write |
GET/getTask | Get a task | read |
GET/listTaskMessages | List a task's messages | read |
POST/sendTaskMessage | Send a follow-up message | write |
POST/stopTask | Stop a task | write |
GET/getTaskShare | Get a task's share link | read |
POST/createTaskShare | Share a task | write |
DELETE/deleteTaskShare | Stop sharing a task | write |
| Files | ||
POST/createFileUpload | Start a file upload | write |
POST/completeFileUpload | Complete a file upload | write |
GET/getFile | Get a file | read |
GET/downloadFile | Download a file | read |
GET/listTaskFiles | List a task's files | read |
| Media | ||
GET/listMediaModels | List media models | read |
GET/listActiveMediaJobs | List running media jobs | read |
GET/getMediaJob | Get a media job | read |
GET/listTaskMediaJobs | List a task's media jobs | read |
| Automations | ||
GET/listAutomations | List automations | read |
POST/createAutomation | Create an automation | write |
GET/getAutomation | Get an automation | read |
PATCH/updateAutomation | Update an automation | write |
DELETE/deleteAutomation | Delete an automation | write |
POST/pauseAutomation | Pause an automation | write |
POST/resumeAutomation | Resume an automation | write |
GET/listAutomationRuns | List an automation's runs | read |
POST/runAutomation | Run an automation now | write |
GET/getAutomationRun | Get an automation run | read |
POST/rotateAutomationWebhookSecret | Rotate a webhook trigger's secret | write |
| Skills | ||
GET/listSkills | List your skills | read |
POST/enableSkill | Turn a skill on | write |
POST/disableSkill | Turn a skill off | write |
| Connectors | ||
GET/listConnectors | List connectors | read |
POST/enableConnector | Turn a connector on | write |
POST/disableConnector | Turn a connector off | write |

