API reference

Everything the dashboard does, an integration can do. 24 resources, 151 actions, 56 webhook events, all of it behind one scoped key.

Authentication

Send your key as a bearer token. X-Api-Key works too.

curl -H "Authorization: Bearer sk_live_..." https://autostud.ai/api/v1

GET /api/v1 answers what can this key do: the resources, actions and limits it holds. Start there instead of hard-coding a route list.

A key prefixed sk_test_ runs the whole request path (authentication, scopes, limits, validation, routing), then stops before any write or credit spend, and answers X-Test-Mode: true.

Scopes

A scope is <resource>:<action>. Wildcards are matched at request time, so videos:* covers a video action added later. write never implies execute: spending credits is its own permission.

Presets

Limits & quotas

Every key carries four rate windows: per minute, per hour, per day, and a separate, much tighter daily budget for anything that spends credits. Heavy endpoints cost more than one unit. Every response reports where you stand:

X-RateLimit-Limit: 120
X-RateLimit-Remaining: 118
X-RateLimit-Reset: 1786500000
X-RateLimit-Window: minute
X-RateLimit-Policy: 120;w=60, 3000;w=3600, 20000;w=86400

A key may also carry a monthly ceiling on requests or on credits (X-Quota-* headers). Both refusals are 429 with Retry-After, and differ by code: rate_limit_exceeded vs quota_exceeded.

Did it work?

One question, one answer, on every endpoint: a response is a failure if and only if it has a top-level error key. Nothing reports success with a success: true flag, and nothing reports failure with a 200. You never have to compare status codes to find out which happened.

{
  "object": "video",
  "id": "vid_8f2c...",
  "video_name": "Quiz - capitals",
  "livemode": true,
  "request_id": "req_8f2c..."
}

object names what you got, so one branch handles every payload. livemode is false when an sk_test_ key produced the response. request_id is on successes as well as failures. It is echoed in the X-Request-Id header, stored in your log at /api/v1/logs, and it is what support will ask for.

Errors

Every failure has the same shape and a stable code to branch on.

{
  "error": {
    "type": "validation_error",
    "code": "validation_failed",
    "status": 422,
    "message": "tools.generate_from_prompt validation failed, `format`: `format` is not allowed (1 more).",
    "param": "format",
    "details": { "issues": [
      { "path": "format", "message": "`format` is not allowed", "type": "object.unknown",
        "allowed": ["prompt", "model", "size", "quality"] },
      { "path": "quallity", "message": "`quallity` is not allowed", "type": "object.unknown",
        "allowed": ["prompt", "model", "size", "quality"], "did_you_mean": "quality" }
    ] },
    "hint": "`details.issues` names each offending field. Fix them and retry; retrying unchanged will fail identically.",
    "retryable": false,
    "livemode": true,
    "request_id": "req_8f2c...",
    "doc_url": "https://autostud.ai/docs/api/errors#validation_failed"
  }
}

Read retryable before you back off. It is false for every client error: repeating the identical request will fail identically, however long you wait, so the fix is in the payload and details says where. It is true only for a rate limit, a conflict, a provider failure or a fault of ours.

internal_error (500) means our code failed; upstream_error (502) means a provider under us did. A wrong request is never either of them.

details.issues has one shape everywhere: path is dotted (config.fps), type is the stable code to branch on, and a field rejected as unknown also carries allowed, the fields that object does take, plus did_you_mean when what you sent was close to one of them. You should never need a second round-trip to find out what a payload accepts.

Health

GET /api/v1/health is the one endpoint that answers without a key. That is the point of it: when a call fails you need to know whether the API is down or your credential is wrong, and an endpoint that returns 401 cannot tell you.

{ "object": "health", "status": "ok", "api_version": "2026-08-14",
  "checks": { "database": { "status": "ok", "latency_ms": 3 } },
  "time": "2026-08-24T09:12:44.108Z" }

It always answers 200; a degraded dependency shows up in status and checks, not in the status code. It reports nothing about your key, your workspace or your usage.

Pagination

Cursor pagination by default, stable while rows are being inserted, and cheap at any depth. Follow next_cursor until has_more is false. offset exists for UIs that need page numbers.

GET /api/v1/videos?limit=50
GET /api/v1/videos?limit=50&cursor=eyJ2Ijp7...

{ "object": "list", "data": [ ... ], "has_more": true, "next_cursor": "eyJ2...", "total": null }

Filtering & search

Filters are declarative: only the fields a resource declares, only these operators. There is no path from a query string to a raw database operator.

?published=true
?video_format[in]=portrait,square
?video_created_at[gte]=2026-01-01
?video_name[starts_with]=Quiz
?q=karaoke&created_after=2026-06-01

Operators: eq (implicit), ne, gt, gte, lt, lte, in, nin, exists, contains, starts_with.

Formats

Any list reads three ways, via ?format= or Accept:.

?fields=a,b narrows the response to what you need; ?expand= brings back the heavy fields a list omits by default.

Idempotency

Send Idempotency-Key on any unsafe request. A replay within 24 hours returns the first response instead of running again, so a retry after a timeout cannot double-charge. Reusing a key with a different body is a 409, not a wrong replay.

curl -X POST https://autostud.ai/api/v1/actions/renders.create \
  -H "Authorization: Bearer sk_live_..." \
  -H "Idempotency-Key: render-2026-08-14-001" \
  -H "Content-Type: application/json" \
  -d '{"video_id": "..."}'

Bulk

POST /api/v1/{resource}/bulk takes up to 100 creates, updates and deletes in one call. Each item reports its own status; the response is 207 when at least one failed. It is not a transaction: successful items stay applied.

{
  "create": [ { "folder_name": "Q3" } ],
  "update": [ { "id": "...", "data": { "folder_name": "Q4" } } ],
  "delete": [ "..." ]
}

Batch

POST /api/v1/batch takes up to 20 different calls in one round trip, sequential by default. Each member goes through its real route: same scopes, same limits, same billing. The envelope is always 200; read each member's own status.

{
  "requests": [
    { "id": "folder", "method": "POST", "path": "/v1/folders", "body": { "folder_name": "Q3" } },
    { "id": "videos", "method": "GET",  "path": "/v1/videos?limit=5" }
  ]
}

Webhooks

Register an https endpoint, subscribe it to events, and stop polling. Deliveries are signed, retried with exponential backoff over ~2 hours, and logged for 7 days.

curl -X POST https://autostud.ai/api/v1/webhooks \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{"url": "https://you.example/hooks", "events": ["render.completed", "video.*"]}'

The signing secret is returned once, on creation. Verify every delivery: X-Autostud-Signature is t=<unix seconds>,v1=<hex>, where the hex is HMAC-SHA256(secret, "<t>.<raw body>"). Reject anything older than five minutes.

const [t, v1] = header.split(',').map(part => part.split('=')[1]);
const expected = crypto.createHmac('sha256', secret)
  .update(t + '.' + raw_body)
  .digest('hex');
// compare with crypto.timingSafeEqual

Deduplicate on X-Autostud-Delivery. Answer 2xx quickly, anything else is retried, and an endpoint that fails 20 times in a row is disabled. POST /api/v1/webhooks/{id}/test sends a real signed delivery and reports what came back.

Event catalog

Subscribe to a name, a family (video.*) or everything (*).

Resources

Actions

Actions are what makes the platform do something. Each one runs the same controller the dashboard calls, so validation, billing and persistence are identical.

Machine-readable spec: /api/v1/openapi.json, import it into Postman, Insomnia or an SDK generator.