Skip to content

API Reference

All endpoints are served over HTTPS at https://api.ipto.ai. Request and response bodies use JSON (application/json) unless otherwise noted. Timestamps are ISO 8601 UTC strings.

Base URL

https://api.ipto.ai

Authentication

Most endpoints require one of the following headers:

Method Header
Session token Authorization: Bearer {token}
API key X-API-Key: ipto_{prefix}_{secret}

See Authentication for details on obtaining tokens and keys.

Endpoint Index

Authentication

Method Path Description Auth Required
POST /v1/auth/signup Create a new account and tenant No
POST /v1/auth/login Log in and obtain a session token No
POST /v1/auth/logout Invalidate the current session Yes

Users

Method Path Description Auth Required
GET /v1/me Get the current user profile Yes
POST /v1/me/password Change the current user's password Yes

Datasets

Method Path Description Auth Required
POST /v1/datasets Create a new dataset Yes
GET /v1/datasets List all datasets Yes
GET /v1/datasets/{id} Get a single dataset Yes
PATCH /v1/datasets/{id} Update a dataset Yes
DELETE /v1/datasets/{id} Delete a dataset Yes

Objects

Method Path Description Auth Required
POST /v1/datasets/{dataset_id}/objects/upload Initiate an object upload Yes
POST /v1/objects/{id}/confirm Confirm a completed upload Yes
DELETE /v1/objects/{id}/upload Cancel a pending upload Yes
GET /v1/datasets/{dataset_id}/objects List objects in a dataset Yes
GET /v1/objects/{id} Get a single object Yes
GET /v1/objects/{id}/download Get a download URL for an object Yes
DELETE /v1/objects/{id} Delete an object Yes

Admin Review

Method Path Description Auth Required
GET /v1/admin/review/queue List objects pending review Yes (Admin)
GET /v1/admin/review/objects/{tenant_id}/{object_id} Get a staged object's detail Yes (Admin)
POST /v1/admin/review/objects/{tenant_id}/{object_id}/approve Approve a staged object Yes (Admin)
POST /v1/admin/review/objects/{tenant_id}/{object_id}/reject Reject a staged object Yes (Admin)
GET /v1/admin/review/objects/{tenant_id}/{object_id}/preview Get a preview URL for a staged object Yes (Admin)

API Keys

Method Path Description Auth Required
POST /v1/api-keys Create a new API key Yes
GET /v1/api-keys List all API keys Yes
GET /v1/api-keys/{id} Get a single API key Yes
DELETE /v1/api-keys/{id} Revoke an API key Yes
POST /v1/api-keys/{id}/grants Grant dataset access to a key Yes
DELETE /v1/api-keys/{id}/grants/{grant_id} Revoke a dataset grant Yes

Provider

Method Path Description Auth Required
GET /v1/provider/dashboard Get provider dashboard summary Yes
GET /v1/provider/datasets/{id}/analytics Get analytics for a dataset Yes
GET /v1/provider/payouts List payout statements Yes

Buyer

Method Path Description Auth Required
GET /v1/buyer/dashboard Get buyer dashboard summary Yes
GET /v1/agent/activity/searches List search activity Yes
GET /v1/agent/activity/accesses List dataset access activity Yes
GET /v1/agent/spend Get spend summary Yes

Health

Method Path Description Auth Required
GET /health Check API health No

Response Envelope

All successful responses are wrapped in a standard envelope:

{
  "data": { ... },
  "request_id": "req_abc123",
  "timestamp": "2026-04-05T10:00:00Z"
}

Error responses use this structure:

{
  "error": {
    "code": "not_found",
    "message": "The requested resource was not found.",
    "details": {}
  },
  "request_id": "req_abc123",
  "timestamp": "2026-04-05T10:00:00Z"
}

Pagination

List endpoints use cursor-based pagination:

Parameter Type Description
cursor string Opaque cursor from a previous response
limit integer Number of results per page (default varies by endpoint)

Rate Limiting

Requests that exceed rate limits receive a 429 Too Many Requests response with a Retry-After header.