Agent API

The Agent API is the same interface the Aspect web app uses to power its AI assistant. You can use it to build your own integrations: create a conversation, send a message to start a run, stream the assistant’s events over SSE, and approve or reject any tool calls that require confirmation. All endpoints live under https://api.aspect.inc/agent and authenticate with an sk_ API key like the rest of the REST API.

Lifecycle

Create a conversation

POST /agent/conversations creates a conversation scoped to a workspace (and optionally a project).

Start a run

POST /agent/conversations/{conversation_id}/runs sends a user message. The response is a Server-Sent Events stream of the run as it executes.

Follow events

GET /agent/conversations/{conversation_id}/events/stream streams the conversation’s event log from any cursor - useful for reconnecting or observing from a second client.

Handle approvals

When a run pauses with requires_approval, submit a decision with POST /agent/runs/{run_id}/approvals/{approval_id}, then resume the run.

Create a conversation

curl -X POST https://api.aspect.inc/agent/conversations \
  -H "Authorization: Bearer sk_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "workspace_id": "9f0b1c2d-3e4f-4a5b-8c6d-7e8f9a0b1c2d",
    "project_id": "1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
    "title": "Footage review"
  }'

workspace_id is required (unless you pass share_id for a share-scoped conversation). project_id and title are optional. The response (201) includes the conversation id, scope, status, and timestamps. Related conversation endpoints:

GET /agent/conversations?workspace_id=...&offset=0&limit=50: list conversations in a scope; supports optional project_id or share_id, returns conversations and has_more.
GET /agent/conversations/{conversation_id}: hydrate a conversation, returning its metadata plus full messages, runs, and tool_calls.
PATCH /agent/conversations/{conversation_id}: update the title.

Start a run

Send a user message. The connection stays open and returns the run’s events as an SSE stream (Content-Type: text/event-stream):

curl -N -X POST https://api.aspect.inc/agent/conversations/{conversation_id}/runs \
  -H "Authorization: Bearer sk_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"content": "Find all clips where someone mentions the product launch"}'

The request body accepts:

Field	Required	Description
`content`	Yes	The user message text.
`content_parts`	No	Structured message content.
`mentions`	No	Structured mentions of resources (projects, assets, collections, and so on).
`page_context`	No	A snapshot of the client’s current page context.
`model`	No	Optional model override.

Stream and list events

Every conversation has an ordered event log with a monotonically increasing integer cursor, so you can resume from wherever you left off:

curl -N "https://api.aspect.inc/agent/conversations/{conversation_id}/events/stream?after_cursor=0" \
  -H "Authorization: Bearer sk_your_api_key"

Event types include run.created, run.status_changed, text.delta, text.completed, tool_call.created, tool_call.updated, tool_call.completed, approval.required, and approval.resolved. Each event carries its cursor, event_type, and a JSON payload. For polling instead of streaming, GET /agent/conversations/{conversation_id}/events?after_cursor=0&limit=100 returns a page of events with has_more and latest_cursor.

For SSE endpoints, the API key can also be passed as an authorization query parameter when your client cannot set request headers.

Approvals

Tools with side effects (creating share links, moving files, and so on) can pause the run with status requires_approval. The approval.required event carries the tool call details and an approval ID. Submit a decision:

curl -X POST https://api.aspect.inc/agent/runs/{run_id}/approvals/{approval_id} \
  -H "Authorization: Bearer sk_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"decision": "approve"}'

decision is approve or reject, with an optional note. The response is the updated run. After deciding, resume the run to continue execution.

Resume and cancel

Resume a paused run - the response is a fresh SSE stream of the continuing run:

curl -N -X POST https://api.aspect.inc/agent/runs/{run_id}/resume \
  -H "Authorization: Bearer sk_your_api_key"

Cancel a run:

curl -X POST https://api.aspect.inc/agent/runs/{run_id}/cancel \
  -H "Authorization: Bearer sk_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"reason": "No longer needed"}'

Run statuses

A run moves through these statuses, reported via run.status_changed events and on run responses: pending → running → (requires_approval | paused) → completed | failed | cancel_requested → cancelled The assistant has the same tool set and permission checks as the in-app experience - it can only see and change what your API key’s user can.

Overview

API Endpoints

Lifecycle

Create a conversation

Start a run

Stream and list events

Approvals

Resume and cancel

Run statuses

​Lifecycle

​Create a conversation

​Start a run

​Stream and list events

​Approvals

​Resume and cancel

​Run statuses

Lifecycle

Create a conversation

Start a run

Stream and list events

Approvals

Resume and cancel

Run statuses