{
  "openapi": "3.0.3",
  "info": {
    "title": "Rekarta API",
    "version": "1.0.0",
    "description": "Send one request, written the way you would write it to Rekarta's chat. Rekarta does all of it on the server (the AI, the drawing, optionally the export) and gives back the result and what you need to go on.\n\nRequests run in the background: `POST /requests` answers at once with an `id`; read the result with `GET /requests/{id}` until `status` is no longer `running`, or give a `callback_url` and Rekarta posts the finished request to it.\n\n**Billing.** Each request is paid from the workspace's credit balance, whatever its plan (an AI edit, a video render and its minutes, an image export). Credit does not expire; a balance holds at most $1,000. The answer says what was charged and what is left. A request that fails before it saves anything costs nothing. When the balance is too low the request is refused with `402 insufficient_credit` before anything is spent.\n\n**Sandbox keys** (`rk_test_...`) answer with a fixed sample, run nothing and cost nothing.\n\n**Retention.** What a request makes (the project, its versions and its files) is not saved in the account. It is kept for a few hours so you can use it again (continue it with `project`, or fetch its files), then deleted, together with what the request asked and answered. The owner of the workspace chooses how long (1 to 168 hours, 6 by default). Save the files you need before then. Only requests made through the API see these projects: they never appear in the web app.\n\n**Plans.** A key needs no subscription: API requests are paid from the credit wallet alone, whatever the workspace's plan.\n\n**Webhooks.** The body is `{\"event\":\"request.finished\",\"data\":<the request>}`. The header `Rekarta-Signature: t=<unix seconds>,v1=<hex>` is the HMAC-SHA256, keyed with the key's webhook secret (`whsec_...`, shown with the key in the web app), of `<t>.<raw body>`. Check it, and reject a `t` more than five minutes old. A reply of 2xx ends the delivery; anything else is tried again after 2 s, 10 s and 60 s."
  },
  "servers": [{ "url": "/v1" }],
  "security": [{ "bearer": [] }],
  "paths": {
    "/requests": {
      "post": {
        "summary": "Start a request",
        "description": "Without `project` Rekarta makes a new project; with it, the request changes that project. Send an `Idempotency-Key` header to make a retry safe: the same key with the same body returns the first request instead of starting another.",
        "parameters": [{ "name": "Idempotency-Key", "in": "header", "schema": { "type": "string", "maxLength": 200 } }],
        "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestIn" } } } },
        "responses": {
          "202": { "description": "Started", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Request" } } } },
          "200": { "description": "The same Idempotency-Key was used with the same body: the first request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Request" } } } },
          "400": { "$ref": "#/components/responses/Error" },
          "401": { "$ref": "#/components/responses/Error" },
          "402": { "$ref": "#/components/responses/Error" },
          "404": { "$ref": "#/components/responses/Error" },
          "409": { "$ref": "#/components/responses/Error" },
          "422": { "$ref": "#/components/responses/Error" },
          "429": { "$ref": "#/components/responses/Error" }
        }
      }
    },
    "/requests/{id}": {
      "get": {
        "summary": "Read a request",
        "parameters": [{ "$ref": "#/components/parameters/id" }],
        "responses": {
          "200": { "description": "The request, as it stands", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Request" } } } },
          "404": { "$ref": "#/components/responses/Error" }
        }
      }
    },
    "/requests/{id}/stop": {
      "post": {
        "summary": "Stop a request that is running",
        "description": "It stops before the next AI call. What was already saved is kept (and paid for).",
        "parameters": [{ "$ref": "#/components/parameters/id" }],
        "responses": { "200": { "description": "Asked to stop" }, "404": { "$ref": "#/components/responses/Error" } }
      }
    },
    "/files": {
      "post": {
        "summary": "Upload a file to use in a request",
        "description": "The body is the file itself (PNG, JPEG, SVG, TTF, OTF). Put the returned `id` in `files` of a request. A file waits for 24 hours and can be used once.",
        "parameters": [{ "name": "name", "in": "query", "required": true, "schema": { "type": "string" } }],
        "requestBody": { "required": true, "content": { "application/octet-stream": { "schema": { "type": "string", "format": "binary" } } } },
        "responses": {
          "200": { "description": "Kept", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "kind": { "type": "string" }, "size": { "type": "string" } } } } } },
          "400": { "$ref": "#/components/responses/Error" },
          "413": { "$ref": "#/components/responses/Error" }
        }
      }
    },
    "/projects/{id}/requests": {
      "get": {
        "summary": "The requests made on a project, oldest first",
        "parameters": [{ "$ref": "#/components/parameters/id" }],
        "responses": {
          "200": { "description": "The requests", "content": { "application/json": { "schema": { "type": "object", "properties": { "requests": { "type": "array", "items": { "$ref": "#/components/schemas/Request" } } } } } } },
          "404": { "$ref": "#/components/responses/Error" }
        }
      }
    },
    "/balance": {
      "get": {
        "summary": "The workspace's credit and what things cost",
        "responses": {
          "200": {
            "description": "The API wallet: what API requests are paid from, whatever the workspace's plan",
            "content": { "application/json": { "schema": { "type": "object", "properties": {
              "plan": { "type": "string" },
              "credit": { "type": "object", "properties": {
                "balanceUSD": { "type": "number" }, "availableUSD": { "type": "number", "description": "the balance minus what running work has been promised" },
                "editUSD": { "type": "number" }, "videoRenderUSD": { "type": "number", "description": "charged for each video render, however short" }, "videoMinuteUSD": { "type": "number", "description": "charged per 1080p minute of video on top of the render fee" }, "imageUSD": { "type": "number" } } } } } } }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": { "bearer": { "type": "http", "scheme": "bearer", "description": "An API key: rk_live_... or rk_test_... (sandbox)" } },
    "parameters": { "id": { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } },
    "responses": {
      "Error": {
        "description": "Every error has a code to act on and words for a person. Codes: unauthorized, invalid_key, key_owner_disabled, rate_limited (see Retry-After), bad_request, bad_callback_url, idempotency_conflict, insufficient_credit, spend_cap, forbidden, not_found, project_busy, too_many_running, too_many_files, file_too_large, ai_unavailable, server_error.",
        "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }
      }
    },
    "schemas": {
      "Error": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } },
      "RequestIn": {
        "type": "object",
        "required": ["prompt"],
        "properties": {
          "prompt": { "type": "string", "maxLength": 4000, "description": "What to make or change, in plain words." },
          "project": { "type": "string", "description": "Change this project instead of making a new one." },
          "files": { "type": "array", "items": { "type": "string" }, "description": "Ids from POST /files." },
          "format": { "type": "string", "enum": ["post", "portrait", "story", "poster", "banner", "landscape", "video", "logo"], "description": "The kind of thing to make, for a new project." },
          "design_system": { "type": "string", "description": "Id of the design system to follow. Empty: the workspace default." },
          "deliver": { "type": "string", "enum": ["png", "jpg", "mp4", "svg", "pdf"], "description": "Also export the new version in this format and return the file in `files`." },
          "max_edits": { "type": "integer", "minimum": 1, "description": "Stop after this many AI edits (at most the server's limit, 6 by default)." },
          "external_user": { "type": "string", "description": "Your own label for the person this is for; it is kept with the request." },
          "callback_url": { "type": "string", "format": "uri", "description": "An https address to post the finished request to (see Webhooks)." }
        }
      },
      "Request": {
        "type": "object",
        "properties": {
          "id": { "type": "string" },
          "status": { "type": "string", "enum": ["running", "done", "needs_input", "failed", "stopped"], "description": "`needs_input`: the AI asked something and saved nothing; answer it with a new request on the same project. While `running`, a requested export may still be under way." },
          "status_line": { "type": "string" },
          "project": { "type": "string" },
          "new_project": { "type": "boolean" },
          "reply": { "type": "string", "description": "What the AI said." },
          "error": { "type": "string" },
          "sandbox": { "type": "boolean" },
          "external_user": { "type": "string" },
          "expired": { "type": "boolean", "description": "True once the result was deleted (see Retention): `versions`, `files` and `reply` are then empty, and `usage` still says what the request cost." },
          "versions": { "type": "array", "items": { "type": "object", "properties": {
            "id": { "type": "string" }, "summary": { "type": "string" },
            "status": { "type": "string", "description": "approved, pending_review, rejected or superseded. Versions made through an API key are approved without review." },
            "live": { "type": "boolean", "description": "Whether this is the version of the project that is live now." },
            "preview_url": { "type": "string", "description": "A picture of the version; the link works for 15 minutes." }, "preview_expires": { "type": "string" } } } },
          "files": { "type": "array", "items": { "type": "object", "properties": {
            "format": { "type": "string" }, "name": { "type": "string" }, "url": { "type": "string", "description": "Download link, valid for 15 minutes; read the request again for a fresh one." },
            "expires": { "type": "string" }, "bytes": { "type": "integer" }, "width": { "type": "integer" }, "height": { "type": "integer" }, "seconds": { "type": "number" }, "version": { "type": "string" } } } },
          "delivery": { "type": "object", "properties": {
            "requested": { "type": "string" }, "status": { "type": "string", "enum": ["none", "pending", "done", "failed"] }, "error": { "type": "string" } } },
          "next": { "type": "object", "properties": {
            "needs_input": { "type": "array", "items": { "type": "string" }, "description": "The questions the AI asked." },
            "suggestions": { "type": "array", "items": { "type": "string" } } } },
          "usage": { "type": "object", "properties": {
            "edits": { "type": "integer" }, "charged_usd": { "type": "number" }, "balance_usd": { "type": "number", "nullable": true } } },
          "created": { "type": "string", "format": "date-time" }
        }
      }
    }
  }
}
