Making Requests¶

This page covers the conventions you need to know for every API call: base URL, headers, request and response formats, pagination, error handling, and rate limiting.

Base URL¶

All API requests are made to:

https://api.ipto.ai

All endpoints are versioned under the /v1 prefix. For example, the datasets endpoint is:

https://api.ipto.ai/v1/datasets

Required Headers¶

Request Format¶

All request bodies use UTF-8 JSON. Timestamps should be ISO 8601 UTC strings (e.g., 2026-04-05T10:00:00Z).

curl -X POST https://api.ipto.ai/v1/datasets \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "name": "Q4 Invoices",
    "description": "Scanned invoice PDFs from Q4 2025",
    "source_modality": "document"
  }'

import uuid
import requests

resp = requests.post(
    "https://api.ipto.ai/v1/datasets",
    headers={
        "Authorization": f"Bearer {token}",
        "Idempotency-Key": str(uuid.uuid4()),
    },
    json={
        "name": "Q4 Invoices",
        "description": "Scanned invoice PDFs from Q4 2025",
        "source_modality": "document",
    },
)

const res = await fetch("https://api.ipto.ai/v1/datasets", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${token}`,
    "Content-Type": "application/json",
    "Idempotency-Key": crypto.randomUUID(),
  },
  body: JSON.stringify({
    name: "Q4 Invoices",
    description: "Scanned invoice PDFs from Q4 2025",
    source_modality: "document",
  }),
});

Response Format¶

Successful Responses¶

Successful responses return a flat JSON object with the resource fields at the top level:

{
  "dataset_id": "dset_abc123",
  "name": "Q4 Invoices",
  "status": "active",
  "created_at": "2026-04-05T10:00:00Z"
}

List endpoints return an array of objects along with pagination metadata:

{
  "items": [
    { "dataset_id": "dset_abc123", "name": "Q4 Invoices", "status": "active" },
    { "dataset_id": "dset_def456", "name": "HR Policies", "status": "active" }
  ],
  "next_cursor": "eyJpZCI6MTIzfQ==",
  "has_more": true
}

Error Responses¶

Errors return a structured envelope with a machine-readable code and a human-readable message:

{
  "error": {
    "code": "invalid_request",
    "message": "The field 'name' is required."
  }
}

Some errors include additional context in a details object:

{
  "error": {
    "code": "invalid_request",
    "message": "Validation failed for 2 fields.",
    "details": {
      "fields": [
        { "field": "name", "reason": "required" },
        { "field": "source_modality", "reason": "must be one of: document, image, audio, video" }
      ]
    }
  }
}

HTTP Status Codes¶

Pagination¶

List endpoints use cursor-based pagination. Pass cursor and limit as query parameters.

Paginating Through Results¶

# First page
curl "https://api.ipto.ai/v1/datasets?limit=10" \
  -H "Authorization: Bearer $TOKEN"

# Next page (use next_cursor from previous response)
curl "https://api.ipto.ai/v1/datasets?limit=10&cursor=eyJpZCI6MTIzfQ==" \
  -H "Authorization: Bearer $TOKEN"

import requests

cursor = None
all_datasets = []

while True:
    params = {"limit": 10}
    if cursor:
        params["cursor"] = cursor

    resp = requests.get(
        "https://api.ipto.ai/v1/datasets",
        headers={"Authorization": f"Bearer {token}"},
        params=params,
    )
    page = resp.json()
    all_datasets.extend(page["items"])

    if not page.get("has_more"):
        break
    cursor = page["next_cursor"]

let cursor: string | undefined;
const allDatasets: any[] = [];

while (true) {
  const params = new URLSearchParams({ limit: "10" });
  if (cursor) params.set("cursor", cursor);

  const res = await fetch(
    `https://api.ipto.ai/v1/datasets?${params}`,
    { headers: { Authorization: `Bearer ${token}` } }
  );
  const page = await res.json();
  allDatasets.push(...page.items);

  if (!page.has_more) break;
  cursor = page.next_cursor;
}

Rate Limiting¶

The API enforces per-tenant rate limits to ensure fair usage. When you exceed the limit, requests return 429 Too Many Requests.

The response includes headers to help you manage your request rate:

FAQ¶