API Reference

The Pictograph API is organized around REST. It has predictable resource-oriented URLs, accepts JSON request bodies, returns JSON responses, and uses standard HTTP response codes and authentication.

Base URL

All API requests should be made to this base URL. Endpoints are appended to this path.

API Architecture

The API follows a hierarchical resource structure:

Organization
├── Datasets (projects)
│   ├── Images
│   │   └── Annotations
│   └── Exports
└── API Keys

• Organization: Your workspace containing all datasets and resources
• Datasets: Collections of images for annotation (called "projects" in the app)
• Images: Individual images within a dataset
• Annotations: Labels attached to images (bboxes, polygons, etc.)
• Exports: Downloadable ZIP archives of annotated datasets

Authentication

Include your API key in the X-API-Key header with every request. See Authentication for details.

Endpoints

Response Format

All responses are JSON. Successful responses return the requested data:

{
  "id": "dataset-uuid",
  "name": "My Dataset",
  "image_count": 150,
  ...
}

Error responses include an error code and message:

{
  "error": "not_found",
  "message": "Dataset not found"
}

HTTP Status Codes

Pagination

List endpoints support pagination with limit and offset parameters:

Pagination Example

// Request: GET /datasets/?limit=2&offset=0

[
  {
    "id": "a1b2c3d4-...",
    "name": "Training Dataset",
    "image_count": 1250,
    "completed_image_count": 1100
  },
  {
    "id": "e5f6g7h8-...",
    "name": "Validation Dataset",
    "image_count": 320,
    "completed_image_count": 320
  }
]

Rate Limit Headers

All responses include headers to help you track your rate limit usage:

# Example response headers
X-RateLimit-Limit: 5000
X-RateLimit-Remaining: 4987
X-RateLimit-Reset: 1706140800

See Rate Limits for detailed information about quotas by plan.