Skip to content

Changelog

Versioning Policy

The IPTO API uses URL-based versioning. All endpoints are prefixed with /v1/. Breaking changes that alter request or response schemas, remove endpoints, or change authentication behavior will increment the version number (e.g., /v2/).

Non-breaking changes are deployed without a version bump. These include:

  • Adding new optional request fields
  • Adding new response fields
  • Adding new endpoints
  • Adding new error codes
  • Relaxing validation constraints
  • Improving error messages

When a new API version is released, the previous version will remain available for a deprecation period to allow migration. Deprecation timelines will be announced in advance.

v1.0.0 -- Initial Release

The first production release of the IPTO API includes the following capabilities:

Authentication & Identity

  • Open signup via POST /v1/auth/signup with automatic tenant and membership creation
  • Session-based login and logout for interactive console users
  • Session management with token-based authentication (Authorization: Bearer <token>)
  • Current principal context via GET /v1/me returning user, tenant, roles, and scopes

Dataset Management

  • Create datasets via POST /v1/datasets with configurable modality, monetization mode, pricing model, and visibility
  • List and retrieve datasets via GET /v1/datasets and GET /v1/datasets/{dataset_id} with summary counters
  • Update dataset metadata via PATCH /v1/datasets/{dataset_id} including name, description, pricing, and visibility
  • Dataset lifecycle states: draft, ingesting, active, paused, suspended, pending_deletion, deleted
  • Dataset visibility modes: private, listed, restricted
  • Marketplace catalog via GET /v1/catalog/datasets for buyer-facing dataset discovery

Object Uploads

  • Presigned URL upload flow via POST /v1/uploads with automatic single-part or multipart strategy selection
  • Upload completion via POST /v1/uploads/{upload_id}/complete triggering normalization pipeline
  • Staged review workflow: all uploads start as review_state=staged and require admin approval before indexing
  • Object metadata and status via GET /v1/objects/{object_id} and GET /v1/datasets/{dataset_id}/objects
  • Object deletion via DELETE /v1/objects/{object_id} with tombstone creation and index cleanup

API Key Management

  • Create API keys via POST /v1/api-keys with configurable scopes and dataset access restrictions
  • List API keys via GET /v1/api-keys for the authenticated tenant
  • Update API keys via PATCH /v1/api-keys/{api_key_id} to modify name, access mode, or dataset list
  • Revoke API keys via DELETE /v1/api-keys/{api_key_id} with immediate effect
  • Scopes: datasets:read, datasets:write, objects:write, search:query, usage:read, keys:write, billing:read, admin:*
  • Dataset access modes: all_available (default) and allow_list for per-key dataset restrictions

Provider Analytics & Payouts

  • Provider analytics via GET /v1/provider/analytics including top keywords, ranking summaries, usage volumes, and revenue breakdowns
  • Payout statements via GET /v1/provider/payouts with per-period gross revenue, earnings, holds, and release status
  • Monthly settlement cycle with dispute and hold window before payout release

Buyer Activity & Spend

  • Search history via GET /v1/agent/activity/searches with filtering by API key and date range
  • Access history via GET /v1/agent/activity/accesses showing datasets and assets accessed
  • Spend summary via GET /v1/agent/spend with grouping by day, dataset, or API key

Admin Review Queue

  • List staged objects via GET /v1/admin/staged-objects with filtering by review state and tenant
  • Approve staged objects via POST /v1/admin/staged-objects/{object_id}/approve to enqueue ingestion
  • Reject staged objects via POST /v1/admin/staged-objects/{object_id}/reject to mark for purge
  • Automatic expiry of unreviewed staged uploads after 48-72 hours

Infrastructure

  • Health check endpoint for monitoring and load balancer integration
  • Idempotency support via Idempotency-Key header on all POST endpoints
  • Cursor-based pagination across all list endpoints
  • Async job tracking via GET /v1/jobs/{job_id} for long-running operations

Coming Soon

Planned features for future releases:

  • Search endpoint enhancements -- full-text search with boolean operators, phrase matching, proximity search, wildcard and regex support, and hybrid lexical/vector retrieval across multiple datasets
  • Webhook notifications -- real-time event delivery for object status changes, review decisions, payout events, and billing milestones
  • Bulk operations -- batch upload initiation, bulk dataset metadata updates, and batch object deletion for high-volume workflows