Developers
REST API endpoint reference
Every public /v1 route with its scope, inputs, response status, and integration boundary, plus the session-only key and webhook management routes.
Updated
Base URL and response conventions
Use https://api.krevaya.com with the paths below. Send a Bearer API key or OAuth access token. JSON requests use Content-Type: application/json. The default success status is 200; creation, asynchronous acceptance, and deletion statuses are called out below. IDs are strings in JSON responses.
Account and post routes
| Method and path | Scope | Input and result |
|---|---|---|
| GET /v1/me | Authenticated key | Returns email, effective plan, scopes |
| GET /v1/posts | read | Query: status_filter (default draft), limit (default 25, clamped 1–100), brand_id. Returns a post array. |
| POST /v1/posts | publish | Required platform, body. Optional hashtags, schedule_at, kind, asset_ids, brand_id, layout, template, design_id. Returns a post receipt (201). |
| POST /v1/posts/{post_id}/favorite | publish | Star a post; returns the post with favorited_at |
| DELETE /v1/posts/{post_id}/favorite | publish | Clear its star; returns the post with favorited_at cleared (200) |
| POST /v1/posts/{post_id}/reject | publish | Optional reason and code; returns id and status |
| PATCH /v1/posts/{post_id}/design | publish | Optional template, layout, layout_version, only_this_post. Re-renders and returns design state and media_paths. |
| POST /v1/generate | generate | Source url or text, optional instruction. Returns source_id and post_ids after generation finishes. |
Media routes
| Method and path | Scope | Input and result |
|---|---|---|
| GET /v1/assets | read | Query: kind, brand_id, q, limit (1–200), cursor. Returns assets, next_cursor, and storage. |
| POST /v1/assets | media | JSON url: public image/video URL. Returns the imported asset (201). |
| POST /v1/assets/upload | media | Raw image bytes; returns the asset (201). This is not multipart/form-data. |
| POST /v1/assets/upload/init | media | JSON filename and size_bytes. Returns upload_id and part_bytes, with an optional direct storage grant. |
| PUT /v1/assets/upload/part | media | Query upload_id and zero-based index; body is raw bytes. |
| POST /v1/assets/upload/finish | media | JSON upload_id and parts (1–80). Returns the video asset (201). |
| DELETE /v1/assets/{asset_id} | media | Delete an owned asset; no response body (204). |
Brand memory routes
| Method and path | Scope | Input and result |
|---|---|---|
| GET /v1/brand-memory | read | Optional brand_id query. Returns brand_id, doc, version, confidence, gaps, updated_at. |
| PATCH /v1/brand-memory | generate | Required expected_version (at least 1), ops (up to 40); optional brand_id. Returns updated state and refused count. |
| POST /v1/brand-memory/import | generate | Optional platforms and brand_id. Returns job_id and status (202). |
| POST /v1/brand-memory/genome | generate | Optional url, run, brand_id. Returns job_id, status, and credits (202). |
Operations exposed through another interface
The REST surface is intentionally smaller than the MCP tool set. Do not construct a /v1 route by guessing from a dashboard request or tool name.
| Task | Supported interface |
|---|---|
| Read one full post | MCP get_post |
| Approve, update copy, schedule, or unschedule an existing post | MCP approve_post, update_post, schedule_post, unschedule_post |
| Read brands or connected accounts | MCP list_brands and list_accounts |
| Create a standalone design or drawing | MCP create_design and create_drawing |
| Edit individual layers or preview a design | MCP get_layers, edit_layers, preview_design |
| Export a video or poll a background job | MCP export_video and job_status |
| Read analytics, queue counts, or the Coach's audit | MCP get_analytics, get_queue_summary, get_audit |
| Manage keys or webhook endpoints | Signed-in session routes /apikeys and /webhooks |
Check both HTTP status and the response body
REST failures normally include detail. A 422 can contain structured validation errors rather than a single sentence. Native layout creation is a special partial-success case: the draft can be created with HTTP 201 while render_error explains that rendering failed. Save its id and retry the design operation on that draft.