Encord

Connect to Encord for data annotation, labeling, and active learning project management.

Add users to project

Add users to an Encord project with a specified role.

Parameters

Parameter	Type	Required	Description
`project_hash`	string	Yes	The ID of the project to add users to
`user_emails`	array	Yes	List of email addresses to add
`user_role`	string	Yes	Role for the users (e.g., annotator, reviewer, admin)

Response

{
  "users_added": [
    {
      "user_email": "new_user@example.com",
      "user_role": "annotator"
    }
  ]
}

Create dataset

Create a new Encord dataset for storing images, videos, and other files.

Parameters

Parameter	Type	Required	Description
`title`	string	Yes	Title for the new dataset
`description`	string	No	Dataset description
`storage_location`	string	No	Where the files are stored: CORD_STORAGE (Encord's own storage), AWS, GCP, or AZURE

Response

{
  "dataset_hash": "new_ds_abc123",
  "title": "My Dataset"
}

Create ontology

Create a new Encord ontology defining annotation categories.

Parameters

Parameter	Type	Required	Description
`title`	string	Yes	Title for the new ontology
`description`	string	No	Ontology description
`structure`	object	No	The ontology's structure in Encord's format, where each object includes id, name, color, shape, and featureNodeHash fields. Leave blank to create an empty ontology.

Response

{
  "ontology_hash": "new_ont_abc123",
  "title": "My Ontology"
}

Create project

Create a new Encord project with specified datasets and ontology.

Parameters

Parameter	Type	Required	Description
`title`	string	Yes	Title for the new project
`dataset_hashes`	array	Yes	The IDs of the datasets to attach to the project
`description`	string	No	Project description
`ontology_hash`	string	No	The ID of the ontology to use for the project

Response

{
  "project_hash": "new_proj_abc123"
}

Create storage folder

Create a new storage folder in Encord.

Parameters

Parameter	Type	Required	Description
`name`	string	Yes	Name of the new folder
`description`	string	No	Folder description
`parent_folder_uuid`	string	No	The ID of the folder to create the new folder in. Leave blank to create it at the top level.

Response

{
  "name": "New Folder",
  "uuid": "f1a2b3c4-d5e6-7890-abcd-ef1234567890"
}

Export labels in COCO format

Export a project's labels in COCO format, a widely used standard for annotation data.

Parameters

Parameter	Type	Required	Description
`project_hash`	string	Yes	The ID of the project to export labels from
`label_hashes`	array	No	The IDs of specific labels to export. Leave blank to export all labels.

Response

{
  "coco_labels": {
    "annotations": [
      {
        "category_id": 1,
        "id": 1,
        "image_id": 1
      }
    ],
    "categories": [
      {
        "id": 1,
        "name": "cat"
      }
    ],
    "images": [
      {
        "file_name": "image_001.png",
        "id": 1
      }
    ]
  }
}

Get dataset details

Retrieve detailed information about a specific Encord dataset.

Parameters

Parameter	Type	Required	Description
`dataset_hash`	string	Yes	The ID of the dataset

Response

{
  "dataset_hash": "ds_abc123",
  "description": "Product training images",
  "title": "Training Images"
}

Get ontology details

Retrieve detailed information about a specific Encord ontology.

Parameters

Parameter	Type	Required	Description
`ontology_hash`	string	Yes	The ID of the ontology

Response

{
  "description": "Bounding box ontology",
  "ontology_hash": "ont_abc123",
  "structure": {
    "classifications": [],
    "objects": []
  },
  "title": "Object Detection"
}

Get project details

Retrieve detailed information about a specific Encord project.

Parameters

Parameter	Type	Required	Description
`project_hash`	string	Yes	The ID of the project

Response

{
  "created_at": "2024-01-15T10:30:00Z",
  "description": "Classify product images",
  "ontology_hash": "ont789xyz",
  "project_hash": "abc123def456",
  "status": "open",
  "title": "Image Classification Project"
}

Get workflow stages

List all workflow stages for an Encord project.

Parameters

Parameter	Type	Required	Description
`project_hash`	string	Yes	The ID of the project to get workflow stages for

Response

{
  "stages": [
    {
      "stage_type": "AnnotationStage",
      "title": "Annotation",
      "uuid": "s1a2b3c4-d5e6-7890-abcd-ef1234567890"
    },
    {
      "stage_type": "ReviewStage",
      "title": "Review",
      "uuid": "s2a2b3c4-d5e6-7890-abcd-ef1234567890"
    }
  ]
}

List datasets

List all Encord datasets, optionally filtering by title.

Parameters

Parameter	Type	Required	Description
`title_like`	string	No	Filter datasets by title (partial match)

Response

{
  "datasets": [
    {
      "created_at": "2024-01-10T08:00:00Z",
      "dataset_hash": "ds_abc123",
      "description": "Product training images",
      "title": "Training Images"
    }
  ]
}

List groups

List all workspace groups in Encord.

Response

{
  "groups": [
    {
      "group_hash": "grp_abc123",
      "name": "Annotation Team"
    }
  ]
}

List label rows

List label rows for an Encord project with optional filters.

Parameters

Parameter	Type	Required	Description
`project_hash`	string	Yes	The ID of the project to list labels from
`data_title_like`	string	No	Filter by data title (partial match)
`label_statuses`	array	No	Filter by label statuses

Response

{
  "label_rows": [
    {
      "annotation_task_status": "COMPLETED",
      "created_at": "2024-02-01T12:00:00Z",
      "data_hash": "data_xyz789",
      "data_title": "image_001.png",
      "label_hash": "lbl_abc123",
      "label_status": "LABELLED"
    }
  ]
}

List ontologies

List all Encord ontologies, optionally filtering by title.

Parameters

Parameter	Type	Required	Description
`title_like`	string	No	Filter ontologies by title (partial match)

Response

{
  "ontologies": [
    {
      "description": "Bounding box ontology",
      "ontology_hash": "ont_abc123",
      "title": "Object Detection"
    }
  ]
}

List project users

List all users with access to an Encord project.

Parameters

Parameter	Type	Required	Description
`project_hash`	string	Yes	The ID of the project to list users for

Response

{
  "users": [
    {
      "user_email": "annotator@example.com",
      "user_role": "annotator"
    }
  ]
}

List projects

List all Encord projects, optionally filtering by title.

Parameters

Parameter	Type	Required	Description
`title_like`	string	No	Filter projects by title (partial match)

Response

{
  "projects": [
    {
      "created_at": "2024-01-15T10:30:00Z",
      "description": "Classify product images",
      "project_hash": "abc123def456",
      "status": "open",
      "title": "Image Classification Project"
    }
  ]
}

List storage folders

List Encord storage folders, optionally searching by name.

Parameters

Parameter	Type	Required	Description
`search`	string	No	Search term to filter folders by name

Response

{
  "folders": [
    {
      "description": "Folder for training images",
      "name": "Training Data",
      "uuid": "f1a2b3c4-d5e6-7890-abcd-ef1234567890"
    }
  ]
}

List storage items

List items in an Encord storage folder.

Parameters

Parameter	Type	Required	Description
`folder_uuid`	string	Yes	The ID of the storage folder
`search`	string	No	Search term to filter items

Response

{
  "items": [
    {
      "item_type": "image",
      "name": "image_001.png",
      "uuid": "i1a2b3c4-d5e6-7890-abcd-ef1234567890"
    }
  ]
}

Move workflow task

Move a task to the next stage or a specific destination in the workflow.

Parameters

Parameter	Type	Required	Description
`project_hash`	string	Yes	The ID of the project
`data_hash`	string	Yes	The ID of the data item whose task you want to move
`stage_uuid`	string	Yes	The ID of the workflow stage the task is currently in
`pathway_name`	string	No	What to do with the task: 'submit' to move annotation work forward, or 'approve' / 'reject' for review tasks
`destination_stage_uuid`	string	No	The ID of the stage to move the task straight to, skipping the normal flow

Response

{
  "status": "success"
}

Upload data to dataset

Add files from your connected cloud storage to an Encord dataset.

Parameters

Parameter	Type	Required	Description
`dataset_hash`	string	Yes	The ID of the dataset to upload the files to
`integration_id`	string	Yes	The ID of your cloud storage integration, found in Encord's settings
`file_urls`	array	Yes	The cloud storage web addresses of the files to add. For advanced options, you can instead provide Encord's upload configuration settings.

Response

{
  "data_hashes": [
    "data_abc123",
    "data_def456"
  ],
  "dataset_hash": "ds_abc123",
  "status": "success"
}

Encord

On this page