Getting Started

Base URL

All API requests are made to:

https://agent-studio.seeyu.ai

OpenAPI specification

Download the complete OpenAPI 3.1 specification as JSON for client generation, request validation, and API tooling.

Quick Start

https://agent-studio.seeyu.ai/workspace/{workspaceId}/w/{workflowId}

curl -X POST https://agent-studio.seeyu.ai/api/v2/workflows/{workflowId}/execute \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -d '{"input": {}}'

const response = await fetch(
  `https://agent-studio.seeyu.ai/api/v2/workflows/${workflowId}/execute`,
  {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'X-API-Key': process.env.STUDIO_API_KEY!,
    },
    body: JSON.stringify({ input: {} }),
  }
)

const data = await response.json()
console.log(data.data.output)

import requests
import os

response = requests.post(
    f"https://agent-studio.seeyu.ai/api/v2/workflows/{workflow_id}/execute",
    headers={
        "Content-Type": "application/json",
        "X-API-Key": os.environ["STUDIO_API_KEY"],
    },
    json={"input": {}},
)

data = response.json()
print(data["data"]["output"])

Sync vs Async Execution

By default, workflow executions are synchronous — the API blocks until the workflow completes and returns the result directly.

For long-running workflows, use asynchronous execution by passing async: true:

curl -X POST https://agent-studio.seeyu.ai/api/v2/workflows/{workflowId}/execute \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -d '{"input": {}, "async": true}'

Keyed callers can optionally provide X-Run-Id: my-run-123 to choose the run ID. Run IDs cannot be reused; a duplicate returns 409.

This returns immediately with a runId and statusUrl:

{
  "data": {
    "runId": "c7a92e15-3f4b-4d8c-a1e6-9b0d5f2c8e74",
    "statusUrl": "https://agent-studio.seeyu.ai/api/v2/workflows/{workflowId}/runs/c7a92e15-3f4b-4d8c-a1e6-9b0d5f2c8e74"
  }
}

Poll the run status endpoint until the status is terminal:

curl "https://agent-studio.seeyu.ai/api/v2/workflows/{workflowId}/runs/{runId}?includeOutput=true" \
  -H "X-API-Key: YOUR_API_KEY"

Response Format

Successful v2 responses wrap the run resource in data:

{
  "data": {
    "runId": "c7a92e15-3f4b-4d8c-a1e6-9b0d5f2c8e74",
    "workflowId": "{workflowId}",
    "status": "completed",
    "output": { "result": "Hello, world!" },
    "error": null,
    "durationMs": 842
  }
}

Error Handling

The API uses standard HTTP status codes. v2 errors include a stable code and human-readable message:

{
  "error": {
    "code": "NOT_FOUND",
    "message": "Workflow not found"
  }
}

Unrecognized fields are rejected

Every v2 endpoint validates the request against its published schema — path parameters, query string, and body — and answers 400 for any field it does not declare. A misspelled parameter is an error rather than a silent no-op, so ?limt=20 fails instead of quietly returning an unbounded list.

This holds for endpoints that declare no query parameters at all. Do not append tracking tags, cache busters, or other extra parameters to a v2 URL; send only what the endpoint documents.

{
  "error": {
    "code": "BAD_REQUEST",
    "message": "Invalid request",
    "details": [
      { "code": "unrecognized_keys", "keys": ["limt"], "path": [], "message": "Unrecognized key: \"limt\"" }
    ]
  }
}

Rate Limits

Rate limits depend on your subscription plan and apply separately to synchronous and asynchronous executions.

Reading your quota

Every response carries the state of the bucket the request was charged against. Read these rather than hardcoding a rate — the ceiling moves with your plan, and X-RateLimit-Limit is the authoritative value for your key at that moment.

How buckets are keyed

v2 meters per operation and per subject. A key that exhausts its budget on POST /api/v2/workflows/{id}/execute can still read logs. Each request is checked against every subject the key resolves to — the API key itself, plus the owning user for a personal key or the workspace for a workspace key — and the most restrictive bucket decides.

v1 is coarser: one shared bucket per user across every v1 endpoint.

Being rate limited

A throttled request returns 429 with the error code RATE_LIMITED:

{
  "error": {
    "code": "RATE_LIMITED",
    "message": "API rate limit exceeded",
    "details": { "retryAfter": "2026-09-08T17:45:00.000Z" }
  }
}

Retry-After gives the wait in whole seconds and details.retryAfter the same instant as a timestamp. Back off until then rather than retrying immediately — a retry before the reset is charged against the bucket and pushes it further out.

Plan gating

On a free plan, running a workflow programmatically — public API, API key, or MCP server — returns 402 with USAGE_LIMIT_EXCEEDED and the message Programmatic workflow execution requires a paid plan. Upgrade to Pro or higher to use the API. Reads are unaffected.

Pagination

List endpoints (workflows, logs, audit logs) use cursor-based pagination:

# First page
curl "https://agent-studio.seeyu.ai/api/v2/logs?workspaceId=WORKSPACE_ID&limit=20" \
  -H "X-API-Key: YOUR_API_KEY"

# Next page — use the nextCursor from the previous response
curl "https://agent-studio.seeyu.ai/api/v2/logs?workspaceId=WORKSPACE_ID&limit=20&cursor=abc123" \
  -H "X-API-Key: YOUR_API_KEY"

The response includes a nextCursor field. When nextCursor is absent or null, you have reached the last page.