Skip to Content
DocumentationAgent API

Agent API

The agent keeps a conversation, plans model calls and returns text or media using your existing balance. Preparation, attachment analysis, context compaction and JSON extraction use the normal model tariffs. There is no separate agent markup. Availability of new runs depends on the storefront. Disabling new runs preserves existing history, downloads and run controls.

All paths below have the /api/v1 prefix. Authenticate with your API key or storefront session, as described in Authentication. Identity and storefront are resolved by the server.

Choose models

GET /agent/models returns the executable public catalog, current prices and verified route capabilities. The main model defaults to gpt-6.1-sol and is used for replies, image analysis and JSON extraction whenever its route supports the operation. Missing capabilities trigger a model-switch proposal in the chat, requiring approval before the alternative model is dispatched. Sol/grsai supports answers, JSON extraction and orchestration through its verified Responses route, including native tool calls and continuation. Gemini 3.8 Flash also has verified native tool routes. Model names alone do not establish support for tools, images or structured output.

GET /agent/settings returns your defaults and their version. Update them with PUT /agent/settings:

{
  "expectedVersion": 0,
  "settings": {
    "orchestratorModelId": "gpt-6.1-sol",
    "fallbackModelIds": ["gemini-3.8-flash", "claude-sonnet-5-5"],
    "imageModelId": "gpt-image-2",
    "videoModelId": "veo3.1-fast",
    "musicModelId": "suno",
    "routingPolicy": "balanced",
    "defaultMaxCostMicroUsd": "2000000"
  }
}

Use the version returned by your own GET; 0 applies only before the first save. Unavailable models and media defaults assigned to the wrong modality are rejected. Explicit fallbacks are tried in order after a confirmed failure and release of its hold. An unknown provider outcome is reconciled before further dispatch.

Settings are isolated by storefront. Project and conversation overrides apply to future runs; each accepted run keeps its settings snapshot. A manual result model stays pinned unless you approve a proposed change.

imageModelId, videoModelId and musicModelId are soft generation defaults. An explicit request in the chat takes priority. The agent may choose another model when inputs are incompatible, including the number of references, and explain why. Project media preferences override user defaults. These defaults do not pin the result model or require approval for a compatible alternative.

Create a conversation and run

Create a conversation with POST /agent/conversations. The body may include title, projectId, profileId, defaultWorkflowId and settings. For a manual result model, set mode: "manual" and selectedModelId. Selecting an LLM manually keeps agent tools, including media generation; it does not pin the image, video or music model. If the selected LLM has no verified tool-calling route, the run waits for model-switch consent instead of falling back to a chat without tools.

List conversations with GET /agent/conversations, ordered by latest activity. Pass q to search titles and message text, and cursor to load the next page. Rename a conversation with PATCH /agent/conversations/{conversationId} (title, expectedVersion). Delete it with DELETE /agent/conversations/{conversationId}; active runs are stopped. In automatic mode, the agent gives an unnamed conversation a short title describing the task.

Send a task to POST /agent/conversations/{conversationId}/messages:

{
  "clientMessageId": "my-task-001",
  "content": [{"type": "text", "text": "Create a square product visual"}],
  "maxCostMicroUsd": "2000000"
}

The response contains conversationId, messageId, runId and status. Keep clientMessageId when retrying the same request. Reusing it with a different body is a conflict. A conversation accepts one active run at a time.

While a run is active, set deliveryMode: "followup" to queue a separate next request with its own limit. At most 20 requests may wait; they execute in order and see the preceding answers. Use deliveryMode: "steer" only when the run view reports canSteer: true: this adds text to the current automatic run at the next step boundary, using the same maxCostMicroUsd. Steering cannot replace its model, files, workflow or final output schema.

Money fields ending in MicroUsd are decimal integer strings: 1000000 is USD 1. The run limit includes settled charges and commitments for operations already started. It is separate from your available account balance. File storage subscriptions use their own explicit quote and payment flow.

Read GET /agent/runs/{runId} for steps, costs and pending actions. Subscribe to GET /agent/conversations/{conversationId}/events for SSE; reconnect with Last-Event-ID containing the last sequence. JSON replay is available at GET /agent/conversations/{conversationId}/event-history?afterSequence=0. Event sequences are ordered within the conversation.

Answer, stop and resume

A run may wait for clarification, model approval, budget or media completion. Clarification replies use the same message endpoint with replyToRunId and the pending questionId; keep that run’s maxCostMicroUsd unchanged.

Approve or reject a pending model change using POST /agent/runs/{runId}/decisions with an Idempotency-Key header and the returned pendingActionId, version, proposalHash and input: {"accept": true}. A stale or expired proposal cannot authorize a new operation. input: {"accept": false} declines the proposed model, clears the pending decision and resumes the run with the selected model preserved. If that model can perform the operation, execution continues on it. Otherwise the run reports model_capability_unavailable with an explanation, without another proposal or dispatching the declined replacement. Declining a switch is not cancellation.

POST /agent/runs/{runId}/stop prevents dependent dispatch and requests cancellation of an active LLM request. An already accepted provider operation may still finish and be charged. An unknown outcome remains under reconciliation; stopping does not turn it into a blind retry or refund.

For a run that can resume, update its total limit with PATCH /agent/runs/{runId}/budget, passing maxCostMicroUsd and the returned budget expectedVersion, then call POST /agent/runs/{runId}/resume. Completed operations are reused.

Attachments and past context

Create an attachment upload with POST /agent/conversations/{conversationId}/attachments, passing name, mime and sizeBytes. PUT the original bytes to the returned uploadUrl without forwarding your API credentials, then call POST /agent/attachments/{attachmentId}/complete. Completion checks the actual type, size and image decoding and creates an immutable original.

A message can reference up to ten files, each at most 25 MiB:

{
  "type": "attachment",
  "attachmentId": "attachment-uuid",
  "usageIntent": "analyze"
}

For a masked edit, include the original image and a PNG mask in the same message. Add "maskFor": {"type": "attachment", "id": "original-uuid"} to the mask attachment block; use "artifact" for an existing generated image. White marks the region to edit, black the region to preserve. The composer’s image viewer provides a brush, eraser, undo and zoom. Each mask uses one of the ten file slots. The platform sends the original and mask together and adds editing instructions; the chosen model must accept multiple image references.

Use auto, analyze, reference or both. Local text extraction is free; model analysis is billed within the run. An unsupported analysis modality is reported explicitly. Originals can be references without an analysis call. Temporary conversation references expire three days after upload completion. Incomplete uploads expire after 24 hours. Reading or using a reference does not extend its TTL. Cleanup runs every minute and retries physical deletion on storage failures; bucket lifecycle also covers orphaned temporary files. Project files and paid retained copies follow their storage subscription, without a three-day age limit. New agent files use public object storage: anyone with a direct object URL can read it until physical deletion. Application endpoints still check ownership and permissions.

Choose past conversations, runs or artifacts with PUT /agent/conversations/{conversationId}/context-references, passing expectedVersion and references, each with targetType and targetId. For conversation sources, targetId accepts an ID or a URL on the current storefront. URLs are parsed locally without an HTTP request. Search uses a local full-text index. An empty list clears access. The agent reads bounded fragments on demand; recursive references do not expand permissions. Each run captures the source boundary, so later messages cannot silently change its input.

Projects and workflows

GET /agent/artifacts/{artifactId} returns the source generationId and outputIndex for an available artifact owned on the current storefront. For media results, use GET /generation/{generationId} to read the prompt, resolution, remaining request parameters and generation metadata. A result without a source generation returns generationId: null.

GET and POST /agent/projects list and create brand projects. A project contains instructions, brand settings, model defaults and immutable versions. PATCH /agent/projects/{projectId} requires expectedVersion. Changes do not rewrite active runs. Project files require an active paid storage plan. Import an available artifact at POST /agent/projects/{projectId}/assets/import with artifactId, an asset role and an Idempotency-Key. It creates a separate copy and returns an operation ID for polling.

GET /agent/profiles lists assistant profiles. GET /agent/workflows lists versioned recipes, including product cards, script-to-video and cover plus music. GET /agent/workflows/{workflowId} returns the input schema and graph. Send workflowId, workflowVersion and workflowInput with your message. Completed nodes are not dispatched again after a restart. Missing required input pauses the run for clarification.

Skills and subtasks

In Auto mode, the agent can apply built-in skills for advertising visuals, image editing, video storyboards and campaign planning. Instructions load when needed. The applied version is frozen for the run and shown in its activity history.

For a multi-part task, the agent can prepare advertising copy and a visual concept as separate subtasks. Each request allows at most two subtasks, each limited to one third of the budget and up to 60 seconds. They use the current orchestrator model, receive only explicitly prepared context and return text. The main agent creates media. Subtask charges count toward the same request limit, and stopping the request stops its subtasks. A single-image generation does not require delegation.

Validated JSON

Send a closed outputSchema on a new run and choose structuredOutputMode: "auto" or "extract". The supported JSON Schema subset forbids external references, open properties and excessive depth. Invalid schemas are rejected before charges.

auto can fill known platform fields deterministically; otherwise extraction uses a billed model call. extract always uses the extractor. A failed parse can use one separately billed repair within the same run limit. A budget pause during extraction resumes finalization rather than repeating media.

GET /agent/runs/{runId}/result returns mainOutcome, revision, artifacts and structuredResult. Only a successful structured result has a value. Failed extraction leaves successful main outputs and their charges intact. The result includes the schema hash, source steps, extraction completion and extraction cost. Downloading or viewing it creates no extra model call.

Storage and webhooks

GET /agent/storage/plans lists all current monthly plans. Obtain a quote with POST /agent/storage/quote, then explicitly accept it at POST /agent/storage/subscribe with its ID, quota version, auto-renew choice and an Idempotency-Key. The quote includes the amount, balance after payment and period. An upgrade charges only the price difference for the remaining part of the paid period. Elapsed time keeps the old price, and the billing date stays unchanged. The next renewal charges the new plan’s monthly price. Renewals debit the shared balance only when enabled. Cancelling renewal keeps files and paid capacity available until the period ends. At that point, a cancelled or failed renewal gives 72 hours to pay or export; further saved-file model reads and writes are paused. Files are deleted after grace expires.

POST /agent/storage/retain starts an idempotent copy of an available source into paid storage. Poll /agent/storage/operations/{operationId}; HTTP 202 means accepted, not copied. GET /agent/storage/files lists owned files with cursor pagination; deletion frees quota without another storage charge.

Create lifecycle webhooks with POST /agent/webhooks, specifying an HTTPS url, eventTypes and a user, project or conversation scope. Copy the signing secret from the creation response; it is shown once. Deliveries keep a stable event ID across retries. Revoke a destination with DELETE /agent/webhooks/{webhookId}.

The internal TypeScript client exports verifyAgentWebhook for raw-body HMAC verification and timestamp checks. Deduplicate verified event IDs at your receiver. Private destinations and DNS rebinding are blocked.

MCP serverOverview
Agent API — API Stock