API reference

This page is a lightweight route reference inside the Sume docs shell. For exact request and response schemas, use the OpenAPI JSON directly.

OpenAPI schema

The current schema snapshot for this preview is available here:

/api/openapi.json

Production Sume serves the live schema here:

https://www.sume.so/api/v1/openapi.json

Download the schema:

curl https://www.sume.so/api/v1/openapi.json \
  -o sume-openapi.json

Authentication

All Public API v1 endpoints use workspace-scoped API keys.

curl https://www.sume.so/api/v1/me \
  -H "Authorization: Bearer $SUME_API_KEY"

Do not pass workspace_id or user_id in request bodies. Sume derives scope from the API key.

Read endpoints

Endpoint	Purpose
GET /me	Read the authenticated user, API key metadata, and workspace context.
GET /credits	Read credit, plan, and active generation capacity.
GET /brand	List sanitized Brand DNA profiles.
GET /brand/current	Read the current workspace Brand DNA profile.
GET /avatars	List usable public and workspace avatars.
GET /avatars/{avatarId}	Read one avatar.
GET /jobs	List workspace-scoped jobs.
GET /jobs/{jobId}	Read one job status.
GET /jobs/{jobId}/result	Read one job result.
GET /assets	List or search indexed Asset Library scene assets.
GET /assets/{assetId}	Read one Asset Library scene asset.

Create endpoints

Generation endpoints may spend credits. Agents should ask for explicit confirmation before calling them unless the user has clearly authorized generation.

Endpoint	Purpose
POST /images/generations	Create an async image generation job.
POST /videos/generations	Create an async video generation job.
POST /ads/videos	Create an async AI Ads video job.
POST /face-swap	Create one or more Face Swap jobs.
POST /reference-analysis	Create a Reference Analysis job for a public TikTok or Instagram Reel URL.
POST /uploads/presign	Create a temporary upload URL for media bytes.
POST /assets	Finalize an uploaded asset and enqueue Asset Library ingest.

Endpoint examples

Check credits:

curl https://www.sume.so/api/v1/credits \
  -H "Authorization: Bearer $SUME_API_KEY"

Search Asset Library scenes:

curl "https://www.sume.so/api/v1/assets?q=product%20demo%20hook&limit=5&sort=relevance" \
  -H "Authorization: Bearer $SUME_API_KEY"

Create an image job:

curl https://www.sume.so/api/v1/images/generations \
  -H "Authorization: Bearer $SUME_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Clean skincare product photo on a white bathroom counter.",
    "aspect_ratio": "1:1",
    "image_count": 1
  }'

Poll and fetch result:

curl https://www.sume.so/api/v1/jobs/job_123 \
  -H "Authorization: Bearer $SUME_API_KEY"

curl https://www.sume.so/api/v1/jobs/job_123/result \
  -H "Authorization: Bearer $SUME_API_KEY"

Errors

Error responses use a consistent envelope:

{
  "error": {
    "code": "invalid_request",
    "message": "A human-readable error message.",
    "details": {}
  },
  "request_id": "req_..."
}

Keep request_id for support, but avoid posting raw private payloads, signed URLs, API keys, user emails, workspace ids, or full media URLs in public logs.