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

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.

  1. Create a key in Vife › Settings › Developer (open it) and export it: export VIFE_API_KEY=vife_sk_…. The secret is shown once.
  2. Create a task with POST /v1/tasks. Send an Idempotency-Key so a retry never starts a second task.
  3. Read GET /v1/tasks/{task_id} until status is completed. result.text holds the answer and result.artifacts the 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"
Response · 202 Accepted
{
  "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#

Common tasks#

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) or read_only (reads only; a write answers 403 read_only_key).
  • Send the key only as Authorization: Bearer vife_sk_…. x-api-key headers and ?api_key= query strings are refused.
  • Admin keys (vife_admin_sk_…) are refused on user operations with 403 admin_key_not_allowed.
GET /v1/me
curl https://api.vife.ai/v1/me -H "Authorization: Bearer $VIFE_API_KEY"
Response · 200 OK
{
  "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"
  }
}
Authentication and permission errors
StatusCodeMeaning
401missing_api_keyNo Authorization: Bearer header.
401invalid_api_keyThe key does not exist.
401api_key_revoked · api_key_expiredThe key was revoked or passed its expiry.
401account_unavailableThe account is suspended or being deleted.
403read_only_keyA read-only key called a write operation.
403admin_key_not_allowedAn 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/v1/tasksCreate a task
  • GET/v1/tasksList tasks (filter by status, source, mode, project, query, dates)
  • GET/v1/tasks/{task_id}Get a task: status, result, error, pending input
  • POST/v1/tasks/{task_id}/messagesAnswer a question or send a follow-up
  • GET/v1/tasks/{task_id}/messagesRead the transcript
  • POST/v1/tasks/{task_id}/stopStop the run
  • POST/v1/tasks/{task_id}/shareMake the task public; DELETE makes it private

Create a task#

POST /v1/tasks
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"}
  }'
Request body
FieldTypeDescription
inputstring, requiredWhat the task should do, or your answer to its question. Up to 200,000 characters.
modestringOne of the eight modes below; agent by default.
optionsobjectThe composer's options, as the web app sends them (for example options.image.selectedModel).
agent_tierstringlite, pro or max (max needs a paid plan). Not for chat.
capabilitiesobjectSkills and connectors for this message, as the composer sends them. Not for chat.
file_idsstring[]Up to 10 ids of files in your account (see Files).
timezonestringYour IANA time zone, such as Europe/Berlin; the agent reads dates in it. Not for chat.
project_idstringPut the task in one of your projects.
metadataobjectUp to 20 string values (keys [A-Za-z0-9_.-], 1-40 characters; values up to 500). Returned on every read and event.
Modes
ModeWhat it does
agentThe default. The full agent plans, researches, browses, uses your skills and connectors, and writes files.
chatA plain conversation with one text model (options.chat.selectedModel): no tools and no queue.
documentThe web app's Document mode: the agent writes a document.
slideThe Slides mode: the agent builds a slide deck.
spreadsheetThe Spreadsheet mode: the agent builds a spreadsheet.
image · video · audioGenerates media through background jobs; see Images, video, audio.

Unknown fields answer 400 unknown_parameter, so a typo never passes silently.

Lifecycle#

Task lifecycle
queuedPOST /v1/tasksrunningtask.needs_input · a messageneeds_inputcompletedtask.completedfailedtask.failedstoppedPOST …/stop

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 values
StatusMeaningWhat to do
queuedAccepted, not running yet (or a follow-up waits).Keep polling or wait for a webhook.
runningThe agent is working.Keep polling or wait for a webhook.
needs_inputThe task waits for you; pending_input says for what.Answer with a message, or act at web_url.
completedDone. result.text and result.artifacts are set.Download the files; send a follow-up to continue.
failederror.code and error.message say why, for example insufficient_credits.Fix the cause and send a new message.
stoppedStopped 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.

GET /v1/tasks/{task_id}
curl https://api.vife.ai/v1/tasks/$TASK_ID -H "Authorization: Bearer $VIFE_API_KEY"
Response · 200 OK
{
  "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).

POST /v1/tasks/{task_id}/messages
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."}'
Response · 202 Accepted (task shortened)
{
  "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}/stop stops the run and returns the task once it settled; it then reads stopped until a new message starts a new turn.
  • POST /v1/tasks/{task_id}/share makes the task public, as the web's Share dialog does, and returns its url; anyone with the link can read it. DELETE makes it private again. A task that holds Google Workspace data is only shared from the web app (403 google_user_data).
  • GET /v1/tasks lists your tasks from every source (api, web, automation), newest first, with limit 1-100 and a cursor.

Read the transcript#

GET /v1/tasks/{task_id}/messages
curl "https://api.vife.ai/v1/tasks/$TASK_ID/messages?order=desc&limit=20" -H "Authorization: Bearer $VIFE_API_KEY"
One entry
{
  "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.

Task errors
StatusCodeWhen
400invalid_request · invalid_options · invalid_capabilities · file_not_foundThe body or one of its files is not valid.
402insufficient_creditsThe balance is at or below zero.
403task_start_blockedThis account cannot start tasks.
404task_not_found · project_not_foundUnknown, deleted or another account's task or project.
409chat_generation_activeA chat task is still answering (Retry-After: 5).
429concurrency_limit_reachedYour plan's running tasks are all busy (Retry-After: 30).
503task_admission_failed · stop_failedRetry 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/v1/files/uploadsStart an upload: presigned PUT URL(s)
  • POST/v1/files/uploads/{upload_id}/completeComplete the upload; answers the stored file
  • GET/v1/files/{file_id}Get a file's details
  • GET/v1/files/{file_id}/contentDownload: a redirect to the file
  • GET/v1/tasks/{task_id}/filesA task's files, inputs and outputs, newest first

Upload a file#

Upload in three calls
# 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, answer parts instead: PUT each 64 MiB byte range to its part url, keep each response's ETag header, 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#

GET /v1/files/{file_id}/content
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.

File errors
StatusCodeWhen
400file_too_largeAbove 1 GiB.
400invalid_upload_token · upload_size_mismatchThe token is for another upload or expired, or the bytes do not match size_bytes.
404file_not_foundUnknown, deleted, still uploading, or another account's file.
409upload_not_received · upload_expiredComplete came before the bytes, or after expires_at.
429upload_limit_reachedToo 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/v1/media/modelsThe selectable models, with inputs, parameters and price (?kind=image|video|audio)
  • GET/v1/tasks/{task_id}/media_jobsA task's media jobs
  • GET/v1/media_jobs/{job_id}One job, with its files once it succeeded
  • GET/v1/media_jobsYour unfinished jobs across tasks
POST /v1/tasks · image
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: false the task first proposes a plan and waits for your approval (needs_input).
  • The task starts background media jobs. A job's status goes from queued through submitted, running and finalizing to succeeded, failed or cancelled; a succeeded job lists its files.
  • Subscribe to media.completed and media.failed instead 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/v1/automationsCreate an automation
  • GET/v1/automationsList automations, newest first
  • PATCH/v1/automations/{automation_id}Change only the fields you send; DELETE removes it
  • POST/v1/automations/{automation_id}/pausePause; …/resume resumes
  • POST/v1/automations/{automation_id}/runsRun it once now (the web's Test run)
  • GET/v1/automations/{automation_id}/runsIts runs (filter all, triggered, failed)
  • POST/v1/automations/{automation_id}/webhooks/{hook_id}/secretRotate a webhook trigger's token
POST /v1/automations · every Monday at 08:00
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 …/runs starts one run per Idempotency-Key, so a retry never starts a second run. It answers 402 insufficient_credits at a balance at or below zero.
  • Subscribe to automation.run.finished to hear when a run ends: success, failed, or not_triggered when the agent found nothing to do. Runs that never started send nothing.
  • For a webhook trigger, POST …/webhooks/{hook_id}/secret returns its token once; every call makes a new token.
  • An automation that targets your Mac runs at ask_for_approval or lower when saved with a key (403 desktop_approval_not_allowed otherwise).

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/v1/skillsYour library and the official skills you can add
  • POST/v1/skills/{skill_id}/enableAdd and turn on; …/disable turns off and keeps it
  • GET/v1/connectorsConnectors with their status (?installed=true for yours)
  • POST/v1/connectors/{connector_id}/enableStart new tasks with it; …/disable stops that
POST /v1/skills/{skill_id}/enable
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_enable says which ones the API can switch on).
  • A connector that is not_connected or needs_sign_in is connected at its connect_url in the web app; enabling it before that answers 409 connector_needs_sign_in or connector_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/v1/accountCredit balance, plan and the key's rate limits
  • GET/v1/account/transactionsYour credit history, newest first (?type=)
GET /v1/account
curl https://api.vife.ai/v1/account -H "Authorization: Bearer $VIFE_API_KEY"
Response fields
FieldContains
creditsbalance, total_earned, total_spent, low_threshold
plancode (basic for a free account), name, status, billing_cycle, current_period_end, auto_renew, concurrent_tasks, monthly_credits, pass
rate_limitstier, 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.

Events
EventSent whendata
task.completedA task's run finished with a result.{task}
task.failedA task's run failed; task.error says why.{task}
task.needs_inputA task waits for an answer or an action.{task}
media.completedA media job succeeded; up to 20 files.{media_job}
media.failedA media job failed (a cancelled job sends nothing).{media_job}
automation.run.finishedAn automation run ended: success, failed or not_triggered.{automation_run, automation}
credits.lowThe balance fell below the low-credit threshold.{balance, threshold, transaction}

Payload and headers#

POST to your endpoint
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
Body
{
  "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)));
  });
}

Delivery 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.

Server
URLhttps://api.vife.ai/v1/mcp
TransportStreamable HTTP, JSON responses, stateless (no session id)
AuthAuthorization: Bearer vife_sk_…; the same rate limits and credits as HTTP calls
ToolsOne 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"

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.

Prompt
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/list lists 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_key argument: pass the same value when a call is retried so it runs once. An Idempotency-Key header on the MCP request is ignored.
  • A tool call runs as the operation's own /v1 request. A non-2xx answer becomes a tool result with isError and the /v1 error 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.

Install
npm install -g @vifeai/cli
vife
vife 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
Exit codes
CodeMeaning
0OK
1Refused by the API
2Usage error
3Key missing or refused
4Rate limited
5Unreachable or server error
6 · 7 · 8tasks 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 body
{
  "error": {
    "type": "invalid_request_error",
    "code": "unknown_parameter",
    "message": "Unknown parameter tittle.",
    "request_id": "6a1f0e2d-3c4b-4a59-8e7d-9f0a1b2c3d4e",
    "param": "tittle"
  }
}
Error types
StatustypeCommon codes
400invalid_request_errorinvalid_request, unknown_parameter, file_not_found, invalid_idempotency_key
401authentication_errormissing_api_key, invalid_api_key, api_key_revoked, api_key_expired
402billing_errorinsufficient_credits
403permission_errorread_only_key, admin_key_not_allowed, skill_pro_required
404not_found_errortask_not_found, file_not_found, route_not_found
409conflict_errorchat_generation_active, upload_not_received, idempotency_request_in_progress
422idempotency_erroridempotency_key_reused
429rate_limit_errorrate_limited, concurrency_limit_reached, upload_limit_reached
500 · 503api_errorinternal_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.

Rate limits (requests per minute)
PlanPer keyPer account, all keys
Free3060
Paid plan120300
  • Running tasks count against your plan's concurrency limit (plan.concurrent_tasks); a task beyond it answers 429 concurrency_limit_reached with Retry-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 with Idempotent-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, 409 idempotency_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#

Size limits
WhatLimit
File1 GiB (one PUT up to 128 MiB, then 64 MiB parts)
Uploads in progress20 per account, 4 of them large
Files per message10 file_ids
Task input200,000 characters
Metadata20 string values, up to 500 characters each, 4 KB in all
List pageslimit 1-100, 20 by default
Event textresult.text up to 4,000 characters and 20 artifacts per task event
MCP request body256 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 · operationIdSummaryAccess
Account
GET/v1/megetMeWho am Iread
GET/v1/accountgetAccountGet your accountread
GET/v1/account/transactionslistAccountTransactionsList credit transactionsread
Tasks
GET/v1/taskslistTasksList tasksread
POST/v1/taskscreateTaskCreate a taskwrite
GET/v1/tasks/{task_id}getTaskGet a taskread
GET/v1/tasks/{task_id}/messageslistTaskMessagesList a task's messagesread
POST/v1/tasks/{task_id}/messagessendTaskMessageSend a follow-up messagewrite
POST/v1/tasks/{task_id}/stopstopTaskStop a taskwrite
GET/v1/tasks/{task_id}/sharegetTaskShareGet a task's share linkread
POST/v1/tasks/{task_id}/sharecreateTaskShareShare a taskwrite
DELETE/v1/tasks/{task_id}/sharedeleteTaskShareStop sharing a taskwrite
Files
POST/v1/files/uploadscreateFileUploadStart a file uploadwrite
POST/v1/files/uploads/{upload_id}/completecompleteFileUploadComplete a file uploadwrite
GET/v1/files/{file_id}getFileGet a fileread
GET/v1/files/{file_id}/contentdownloadFileDownload a fileread
GET/v1/tasks/{task_id}/fileslistTaskFilesList a task's filesread
Media
GET/v1/media/modelslistMediaModelsList media modelsread
GET/v1/media_jobslistActiveMediaJobsList running media jobsread
GET/v1/media_jobs/{job_id}getMediaJobGet a media jobread
GET/v1/tasks/{task_id}/media_jobslistTaskMediaJobsList a task's media jobsread
Automations
GET/v1/automationslistAutomationsList automationsread
POST/v1/automationscreateAutomationCreate an automationwrite
GET/v1/automations/{automation_id}getAutomationGet an automationread
PATCH/v1/automations/{automation_id}updateAutomationUpdate an automationwrite
DELETE/v1/automations/{automation_id}deleteAutomationDelete an automationwrite
POST/v1/automations/{automation_id}/pausepauseAutomationPause an automationwrite
POST/v1/automations/{automation_id}/resumeresumeAutomationResume an automationwrite
GET/v1/automations/{automation_id}/runslistAutomationRunsList an automation's runsread
POST/v1/automations/{automation_id}/runsrunAutomationRun an automation nowwrite
GET/v1/automations/{automation_id}/runs/{run_id}getAutomationRunGet an automation runread
POST/v1/automations/{automation_id}/webhooks/{hook_id}/secretrotateAutomationWebhookSecretRotate a webhook trigger's secretwrite
Skills
GET/v1/skillslistSkillsList your skillsread
POST/v1/skills/{skill_id}/enableenableSkillTurn a skill onwrite
POST/v1/skills/{skill_id}/disabledisableSkillTurn a skill offwrite
Connectors
GET/v1/connectorslistConnectorsList connectorsread
POST/v1/connectors/{connector_id}/enableenableConnectorTurn a connector onwrite
POST/v1/connectors/{connector_id}/disabledisableConnectorTurn a connector offwrite