Sign In Get Started

Annotations API

API endpoints for creating, reading, and managing annotations.

Annotations are the labeled regions on images - bounding boxes, polygons, polylines, and keypoints. These endpoints allow full CRUD operations on annotations.

Get Annotations

GET /api/v1/developer/annotations/{image_id}

Get all annotations for an image.

Example

from pictograph import Client

client = Client(api_key="{{API_KEY}}")
annotations = client.annotations.get("{{IMAGE_ID}}")

for ann in annotations:
    print(f"Class: {ann['name']}, Type: {ann['type']}")
import requests

response = requests.get(
    "https://api.pictograph.io/api/v1/developer/annotations/{{IMAGE_ID}}",
    headers={"X-API-Key": "{{API_KEY}}"}
)
data = response.json()
annotations = data["annotations"]
curl https://api.pictograph.io/api/v1/developer/annotations/{{IMAGE_ID}} \
  -H "X-API-Key: {{API_KEY}}"
const response = await fetch(
  "https://api.pictograph.io/api/v1/developer/annotations/{{IMAGE_ID}}",
  { headers: { "X-API-Key": "{{API_KEY}}" } }
);
const { annotations } = await response.json();
req, _ := http.NewRequest("GET",
    "https://api.pictograph.io/api/v1/developer/annotations/{{IMAGE_ID}}", nil)
req.Header.Set("X-API-Key", "{{API_KEY}}")

resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()

var result struct {
    Annotations []map[string]interface{} `json:"annotations"`
}
json.NewDecoder(resp.Body).Decode(&result)
Response Click to collapse Click to expand
JSON 
{
  "image_id": "550e8400-e29b-41d4-a716-446655440000",
  "annotations": [
    {
      "id": "ann-uuid-1",
      "name": "person",
      "type": "bbox",
      "bounding_box": {
        "x": 100,
        "y": 200,
        "w": 50,
        "h": 120
      },
      "confidence": 1.0
    },
    {
      "id": "ann-uuid-2",
      "name": "car",
      "type": "polygon",
      "polygon": {
        "path": [
          {"x": 300, "y": 400},
          {"x": 450, "y": 400},
          {"x": 475, "y": 500},
          {"x": 275, "y": 500}
        ]
      }
    }
  ]
}

Get Annotations (Export Format)

GET /api/v1/developer/annotations/{image_id}/file

Get annotations in the full export file format (includes image metadata).

Example

curl https://api.pictograph.io/api/v1/developer/annotations/{{IMAGE_ID}}/file \
  -H "X-API-Key: {{API_KEY}}"
import requests

response = requests.get(
    "https://api.pictograph.io/api/v1/developer/annotations/{{IMAGE_ID}}/file",
    headers={"X-API-Key": "{{API_KEY}}"}
)
export_format = response.json()
const response = await fetch(
  "https://api.pictograph.io/api/v1/developer/annotations/{{IMAGE_ID}}/file",
  { headers: { "X-API-Key": "{{API_KEY}}" } }
);
const exportFormat = await response.json();
Response Click to collapse Click to expand
JSON 
{
  "image": "scene_001.jpg",
  "image_url": "https://api.pictograph.io/api/v1/developer/images/img-uuid",
  "image_uuid": "img-uuid",
  "image_path": "/scenes",
  "annotation_count": 2,
  "annotation_url": "https://app.pictograph.io/project/proj-id/annotate/scene_001.jpg",
  "dataset": {"name": "Street Scenes", "slug": "street-scenes"},
  "org": {"name": "My Org", "slug": "my-org"},
  "annotations": [...]
}

Save Annotations

POST /api/v1/developer/annotations/{image_id}

Save annotations for an image. This replaces all existing annotations.

Request Body

JSON 
{
  "annotations": [
    {
      "id": "ann-uuid-1",
      "name": "person",
      "type": "bbox",
      "bounding_box": {
        "x": 100,
        "y": 200,
        "w": 50,
        "h": 120
      }
    },
    {
      "id": "ann-uuid-2",
      "name": "car",
      "type": "polygon",
      "polygon": {
        "path": [
          {"x": 300, "y": 400},
          {"x": 450, "y": 400},
          {"x": 475, "y": 500},
          {"x": 275, "y": 500}
        ]
      }
    }
  ]
}

Validation Rules

  • id - Required, must be unique within the image
  • name - Required, the class name (NOT class)
  • type - Required, one of: bbox, polygon, polyline, keypoint
  • Type-specific field required (e.g., bounding_box for bbox type)

Example

from pictograph import Client

client = Client(api_key="{{API_KEY}}")
annotations = [
    client.annotations.create_bbox("ann-1", "person", [100, 200, 50, 120]),
    client.annotations.create_polygon("ann-2", "car", [[300, 400], [450, 400], [475, 500], [275, 500]])
]
client.annotations.save("{{IMAGE_ID}}", annotations)
import requests

response = requests.post(
    "https://api.pictograph.io/api/v1/developer/annotations/{{IMAGE_ID}}",
    headers={
        "X-API-Key": "{{API_KEY}}",
        "Content-Type": "application/json"
    },
    json={
        "annotations": [
            {
                "id": "ann-1",
                "name": "person",
                "type": "bbox",
                "bounding_box": {"x": 100, "y": 200, "w": 50, "h": 120}
            }
        ]
    }
)
curl -X POST https://api.pictograph.io/api/v1/developer/annotations/{{IMAGE_ID}} \
  -H "X-API-Key: {{API_KEY}}" \
  -H "Content-Type: application/json" \
  -d '{
    "annotations": [
      {
        "id": "ann-1",
        "name": "person",
        "type": "bbox",
        "bounding_box": {"x": 100, "y": 200, "w": 50, "h": 120}
      }
    ]
  }'
const response = await fetch(
  "https://api.pictograph.io/api/v1/developer/annotations/{{IMAGE_ID}}",
  {
    method: "POST",
    headers: {
      "X-API-Key": "{{API_KEY}}",
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      annotations: [
        {
          id: "ann-1",
          name: "person",
          type: "bbox",
          bounding_box: { x: 100, y: 200, w: 50, h: 120 }
        }
      ]
    })
  }
);
annotations := map[string]interface{}{
    "annotations": []map[string]interface{}{
        {
            "id":   "ann-1",
            "name": "person",
            "type": "bbox",
            "bounding_box": map[string]int{
                "x": 100, "y": 200, "w": 50, "h": 120,
            },
        },
    },
}
jsonBody, _ := json.Marshal(annotations)

req, _ := http.NewRequest("POST",
    "https://api.pictograph.io/api/v1/developer/annotations/{{IMAGE_ID}}",
    bytes.NewBuffer(jsonBody))
req.Header.Set("X-API-Key", "{{API_KEY}}")
req.Header.Set("Content-Type", "application/json")

resp, _ := http.DefaultClient.Do(req)

Delete Annotations

DELETE /api/v1/developer/annotations/{image_id}

Delete all annotations for an image.

Example

from pictograph import Client

client = Client(api_key="{{API_KEY}}")
client.annotations.delete("{{IMAGE_ID}}")
import requests

response = requests.delete(
    "https://api.pictograph.io/api/v1/developer/annotations/{{IMAGE_ID}}",
    headers={"X-API-Key": "{{API_KEY}}"}
)
curl -X DELETE https://api.pictograph.io/api/v1/developer/annotations/{{IMAGE_ID}} \
  -H "X-API-Key: {{API_KEY}}"
await fetch(
  "https://api.pictograph.io/api/v1/developer/annotations/{{IMAGE_ID}}",
  {
    method: "DELETE",
    headers: { "X-API-Key": "{{API_KEY}}" }
  }
);
req, _ := http.NewRequest("DELETE",
    "https://api.pictograph.io/api/v1/developer/annotations/{{IMAGE_ID}}", nil)
req.Header.Set("X-API-Key", "{{API_KEY}}")

resp, _ := http.DefaultClient.Do(req)

Batch Download Annotations

GET /api/v1/developer/annotations/dataset/{dataset_id}/download

Get download URLs for all annotations in a dataset.

Example

import requests

response = requests.get(
    "https://api.pictograph.io/api/v1/developer/annotations/dataset/{{DATASET_ID}}/download",
    headers={"X-API-Key": "{{API_KEY}}"}
)
data = response.json()
curl https://api.pictograph.io/api/v1/developer/annotations/dataset/{{DATASET_ID}}/download \
  -H "X-API-Key: {{API_KEY}}"
const response = await fetch(
  "https://api.pictograph.io/api/v1/developer/annotations/dataset/{{DATASET_ID}}/download",
  { headers: { "X-API-Key": "{{API_KEY}}" } }
);
const { annotations } = await response.json();
Response Click to collapse Click to expand
JSON 
{
  "annotations": [
    {
      "image_id": "img-uuid-1",
      "filename": "scene_001.jpg",
      "url": "/api/v1/developer/annotations/img-uuid-1/file"
    },
    {
      "image_id": "img-uuid-2",
      "filename": "scene_002.jpg",
      "url": "/api/v1/developer/annotations/img-uuid-2/file"
    }
  ]
}
Copied to clipboard