Skip to main content
DOCS

Data & APIs

Typed REST endpoints generated from your spec, with pagination, idempotent writes, and natural-language queries.

Typed REST, generated from your spec

The data side of your generated backend: every asset in your spec gets REST endpoints with typed request/response contracts, covering field types, required flags, enums, foreign-key references, and descriptions. Use the SDK directly in your app code; no ORMs, mappers, or hand-written types needed.

Endpoint contract (from the generated spec)
{
  "method": "GET",
  "path": "/books/{id}",
  "responses": {
    "200": {
      "schema": {
        "id":       { "type": "string" },
        "title":    { "type": "string" },
        "isbn":     { "type": "string", "unique": true },
        "authorId": { "type": "string", "foreignKey": { "referencedAsset": "Author" } }
      }
    }
  }
}

Reading data

// Collections support pagination out of the box
const page = await ws.get("/books", { limit: "10", offset: "0" });
// → { data: [...], total, hasMore }

// Single records
const book = await ws.get("/books/123");

Writing data

const created = await ws.post("/books", { title: "The Ring" });
const updated = await ws.put("/books/123", { title: "New title" });
const patched = await ws.patch("/books/123", { status: "archived" });
await ws.delete("/books/123");

Idempotent writes

Pass an idempotency key with any write to guard against retries creating duplicates. The same key on a retry returns the cached response (kept for 24 hours); a different key creates a new record.

Natural-language queries

Connected agents can also query with plain English via the query_data MCP tool — Codata translates to SQL, runs it read-only, and returns the rows together with the SQL that ran, so results are verifiable.

query_data({ query: "the 10 most recent orders by amount" })
// → { sql: "SELECT ...", rows: [...], rowCount, explanation }

Golden rule: use the SDK response shapes directly. Don't add mappers, adapters, or duplicate interfaces — the Codata types are the single source of truth.