Labelbox GraphQL API
What is GraphQL?
GraphQL is an API query language and a server-side runtime for executing queries. Everything in GraphQL revolves around a schema, which represents all the data in your system and the type of data it is.
Why does Labelbox use GraphQL?
We chose to use GraphQL to structure our API because it provides more flexibility than REST. Here are some advantages GraphQL offers:
Strongly-typed schema
Both the request query and the response are strongly typed. You will know your query is valid because the schema will not allow improperly written schemas.
Hierarchical structure
Each GraphQL query and response takes the shape of a hierarchical set of fields. This makes the queries easy to create and the responses intuitive to read.
Flexibility
With GraphQL you can get all the data you need in one single request allowing for quicker, more precise data retrieval.
Specificity
Unlike in a REST API, a GraphQL response will include only the data you specify in your query.
Strong tooling
Tools like our API explorer allow you to explore the API schema and run queries in your browser.
Root operation types
Our GraphQL API makes use of two operation types, Query and Mutation. These are special because they provide the entry point for every GraphQL query. We encourage you to experiment with these operation types in our API explorer.
Fields, arguments & object types
Fields, arguments, and object types are used to construct the schema. The Query
fields perform read-only operations and the Mutation
fields perform writes.
The createLabel
example below is a Mutation
field.

Fields allow you to perform specialized operations within the Query
and Mutation
root operation types. The createLabel
field in the example above requires an argument and targets the Label
object type.
Arguments are defined by name and type and serve a variety of purposes. Each field can have zero or more arguments. In the example above, the data: LabelCreateInput
argument is required as specified by the (!) symbol.
Object types are the entities in the database that receive the action performed by the field. For the createLabel
field, the Label
object type is required as specified by the (!) symbol.
Using the API explorer
In the API explorer, run the following query:
This query retrieves your own user information. In GraphQL terminology, user
is our root object from which we select all of its fields we want to retrieve (id
, email
, role
) and a sub-object: organization
. Hovering over the syntax will give more information about each object/field.
The Documentation Explorer to the upper right provides more Schema details; try searching "User" to explore other fields you can select.
![]() |
query getUserInfo { user{ id email role organization{ id name } projects{ id name } } }
Creating parameterized queries
We can use some of the data we just retrieved to construct a more involved query. Copy and paste the project ID into the Query Variables section in the bottom left pane, like so:
{ "project_id" : "<PROJECT ID HERE>" }
In the main text window, run the following:
This time, we've created a function for our query by naming it byProjects()
and assigning it a parameter, $project_id
of type ID
. In the bottom pane, we've tossed our function an argument for project ID. The resulting data is the member info for only the project we specified.
query byProjects($project_id: ID!) { projects(where: {id_contains: $project_id}) { members{ user{ email id role } } } }
Getting started
Root endpoint
https://api.labelbox.com/graphql
Create API key
Click “Account” from the upper-right dropdown menu.
From the API tab, click “Create API Key”.
Copy the API key to your clipboard by clicking the blue icon. The API key will be hidden once you leave this page so make sure to save your API Key somewhere else.
Authentication
Authentication tokens (API Keys) are accepted by our GraphQL API in one of two ways.
Provide as an authorization header [RECOMMENDED]:
Provide as a query parameter. We do not recommend sending API keys as a query parameter for GraphQL queries.
# Pass API key as a header to make a graphql query curl 'https://api.labelbox.com/graphql' \ -H 'Authorization: Bearer <API_KEY_HERE>' \ -H 'content-type: application/json' \ -d '{"query":"[QUERY HERE]"}' # Pass API key as a header to request a mask for an annotated object curl 'https://api.labelbox.com/masks/feature/:id' \ -H 'Authorization: Bearer <API_KEY_HERE>'
# Passing API key as a query parameter to request a mask for an annotated object curl 'https://api.labelbox.com/masks/feature/:id?token=<API_KEY_HERE>'
Annotation counts
Annotation count is the sum of the billable annotations created by the team members in your organization.
Get annotation count
To get the billable annotation count for your organization, use the annotationCounts
query and specify a date range. If startDate
and endDate
are both absent, the API returns all available data.
This sample query will get the annotation counts for a single date, 02/08/2021.
Field | Type | Description |
---|---|---|
| Date | UTC date in |
| Date | UTC date in |
| Enum | Values are: |
The annotationCounts
query returns a list of AnnotationCount
objects with the following properties.
Field | Type | Description |
---|---|---|
| Int | Cumulative counts of image annotations for the specified date. |
| Int | Cumulative counts of video annotations for the specified date. |
| Int | Cumulative counts of text annotations for the specified date. |
| Date | If annotation counts are not available for a given date, that date's |
| DateTime | When |
query GetAnnotationCount { annotationCounts (where: {startDate: "2021-02-08", endDate: "2021-02-09"}, orderBy: CREATION_DATE_ASC){ image video text creationDate updateTime } }
Attachments (Asset metadata)
Attachments are media you can attach to a Data Row to provide labelers with contextual information about the asset to be labeled.
To learn more about how to use attachments, see Attachments.
Add attachments
To attach more than one image, video, or text string, you will need to run the createAssetMetadata
mutation multiple times which will append the subsequent it to the list of existing asset metadata.
To add attachments to a Data Row, use the createAssetMetadata
mutation.
Field | Type | Description |
---|---|---|
| ID | ID of the Data Row to add the attachments to |
| String | Accepts an |
| AttachmentType | Values are:
|
mutation addAssetInfo { createAssetMetadata( data: { dataRowId:"<DATAROW-ID>", metaValue:"https://firebasestorage.googleapis.com/v0/b/labelbox-193903.appspot.com/o/cjhk4p9dyf5va0702liitudpz%2Fd3ffab29-d6be-4d69-b006-89a828679d29%2Fleft_small-pen-test-site_1_1537524039648.jpg?alt=media&token=66e84e55-97e8-46a6-9ab8-685f1e950581", metaType: IMAGE } ) { id } }
Edit attachments
First, use this query to get the ID for the attachments.
Then, use the updateAssetMetadata to update the attachments.
Field | Type | Description |
---|---|---|
| ID | ID of the Data Row to add the attachments to |
| String | Accepts an |
| AttachmentType | Values are:
|
query getMetadataId { dataRow (where: {id: "<DATAROW_ID>"}) { id metadata { id } } }
mutation updateAssetInfo { updateAssetMetadata( where:{ id:"<METADATA-ID>" }, data:{ metaValue:"https://storage.googleapis.com/labelbox-sample-datasets/nlp/lorem-ipsum.txt", metaType: TEXT } ){ id } }
Remove attachments
First, use the dataRow
query to get the attachment IDs.
Then, use the deleteAssetMetadata
mutation to remove the attachments.
query getMetadataId { dataRow (where: {id: "<DATAROW_ID>"}) { id metadata { id } } }
mutation removeAssetInfo { deleteAssetMetadata( where:{ id:"<METADATA-ID>" } ){ id } }
Bulk import requests
bulkImportRequest
represents the bulk import job for a set of predictions.
For an overview of this workflow, see our docs on Model-assisted labeling.
Create a bulk import request
After you create your NDJSON file, create a public URL for your file. Then, use the createBulkImportRequest
mutation to create an import job.
Field | Type | Description |
---|---|---|
| ID | Project to import the annotations |
| String | Name of the import job |
| String | Valid URL to an NDJSON file containing the annotations |
Caution
Wait until the import job is complete before opening the Editor to make sure all annotations are imported properly.
mutation { createBulkImportRequest(data: { projectId: "<PROJECT_ID>", name: "import_job_1", fileUrl: "https://foobar.com/test2file" }) { id } }
Check import request status
Use the bulkImportRequest
query to check the status of the import job.
This query returns the following fields.
Field | Type | Definition |
---|---|---|
| BulkImportRequestState | Refers to the whole import job and the values are: |
| String | Points to an NDJSON that expires after 24 hours and contains a |
| String | Points to an NDJSON that contains error messages for each annotation that did not import successfully when state is |
query { bulkImportRequest(where: { projectId: "<PROJECT_ID>", name: "import_job_1" }) { state statusFileUrl errorFileUrl } }
List all import requests
Use this bulkImportRequests query to return a list of each import request that is accessible to you (Note: bulkImportRequests
is plural). Use the following arguments to filter your query.
Argument | Type | Description |
---|---|---|
| Int | Indicates the number of items to skip over. |
| PageSize | Indicates the max number of items to return. |
query ListAllImportRequests { bulkImportRequests ( where: { projectId:"ckg2izcjx5qm10736kqg128yq" } skip: 5 first: 100 ) { id name } }
Delete imported annotations
Use this mutation to delete all imported annotations associated with a bulkImportRequest
(note: this mutation does not delete the import request itself).
Labelbox handles each deleteBulkImportRequest
atomically, meaning either all or none of the annotations will be deleted depending on whether or not the deletion is successful.
If you open the asset with the imported annotations in the Editor before using the deleteBulkImportRequest
mutation, you may need to refresh the screen to see the annotations removed from the labeling interface.
mutation DeleteBulkImportRequest { deleteBulkImportRequest(where: {id: "<IMPORT_REQUEST_ID>"}) { id name } }
Data Rows
A Data Row is the internal Labelbox representation of an asset.
Bulk import
Before you import, make sure your JSON file is formatted properly for the data type you are importing. Then, use the appendRowsToDataset
mutation to create data rows from the JSON file.
Field | Type | Definition |
---|---|---|
| ID | Dataset ID |
| String |
|
mutation AppendRowsToDataset { appendRowsToDataset( data:{ datasetId:"<DATASET_ID>", jsonFileUrl:"<URL_TO_JSON_FILE>" } ){ accepted } }
Individual import
Use the createDataRow
mutation to import data by URL and attach it to an existing project.
Field | Type | Definition |
---|---|---|
| String | User generated filename |
| String | An |
| ID | Dataset to connect the data row to |
mutation CreateDataRow { createDataRow( data: { externalId: "<EXTERNAL_ID>", rowData: "<ASSET_URL>", dataset: { connect: { id: "<DATASET_ID>" } }, } ){ id } }
Get all data rows in a dataset
Use the datasets
query to return all dataRows
from a dataset. For a complete list of fields for data rows, see the Docs tab in the API explorer.
query GetDataRows { datasets (where: {id: "<DATASET_ID>"}) { name id dataRows { id externalId } } }
Get all data rows in a project
Use the dataRows
query within a project
query to get all data rows from a project. For a complete list of arguments for dataRows
see the Docs tab in the API explorer.
query GetDataRowsByProject { project (where: {id: "<PROJECT_ID>"}) { datasets { dataRows (first: 100){ id rowData externalId } } } }
Update data rows
Use the updateDataRow
mutation to update data row fields.
Field | Type | Definition |
---|---|---|
| String | User-generated file name |
| String | https URL to the asset to be labeled |
mutation UpdateDataRow { updateDataRow( where:{id: "<DATAROW_ID>"} data:{ externalId: "<NEW_FILENAME>", rowData: "<NEW_ASSET_URL>" } ){ id }
Delete data rows
The deleteDataRows
mutation can take a list of up to 10,000 dataRowIds
.
Caution
Cascading delete - if you delete a data row it will also delete the attached labels. Once deleted, there is no API method to undelete a data row.
mutation DeleteDataRows { deleteDataRows (where:{ dataRowIds: ["<DATA_ROW_ID>"] }){ id deleted } }
Datasets
A Dataset is a collection of Data Rows and can span multiple Projects. For a complete list of fields for Dataset, visit the Docs tab in the API explorer.
Create a dataset
Use the createDataset
mutation to create a dataset and connect it to a project.
Field | Type | Description |
---|---|---|
| String | Dataset name |
| ID | ID of the project to connect the dataset to |
mutation CreateDataset { createDataset ( data: { name: "dataset name", projects: { connect: { id: "ck6cib5zmmy3g0842s3bdkl6t" } } } ) { id } }
Attach a dataset
Use the updateProject
mutation to connect an existing dataset to a project.
Field | Type | Description |
---|---|---|
| ID | ID of the dataset to connect to the project |
mutation AttachDataset{ updateProject( where:{ id:"ck6cib5zmmy3g0842s3bdkl6t" }, data:{ datasets:{ connect:{ id: "ck52rvx4ombr80853k1ccx1s2" } } } ){ id } }
Get a dataset
Use the dataset
query to get a dataset by id. For a complete list of Dataset fields, see the Docs tab in the API explorer.
query GetDataset { dataset (where: {id: "ck7us46zn1ial0807z9esamua"}) { name description projects { id } createdAt createdBy { id } rowCount } }
Update a dataset
Use the updateDataset
mutation to update dataset fields.
Field | Type | Description |
---|---|---|
| string | Dataset name |
| string | Dataset description |
mutation UpdateDataset { updateDataset ( where: { id: "ck52rvx4ombr80853k1ccx1s2" }, data: { name: "new name", description: "new description" } ) { id } }
Delete a dataset
Use the updateDataset
mutation to delete a dataset.
Field | Type | Description |
---|---|---|
| boolean | To delete a dataset, set to |
mutation UpdateDataset { updateDataset ( where: { id: "ck52rvx4ombr80853k1ccx1s2" }, data: { deleted: true } ) { id } }
Integrations
Use these GraphQL operations to configure IAM Delegated Access programmatically. To learn more, see our Delegated Access docs.
To view a sample script for setting this up, see our IAM Delegated Access colab notebook.
Integration setup
Follow these steps to set up IAM Delegated Access via the GraphQL API.
Use the
createAwsIamIntegration
mutation to create a new AWS IAM integration. See a sample mutation here. Theid
value returned is the Labelbox External ID. The Labelbox AWS account ID is340636424752
.Follow steps 3-4 in the Configure integration in AWS docs to set up the role and permission policy for Labelbox in your AWS account.
In your AWS account, go to Services > IAM > Roles, click on your newly created role, and copy the Role ARN (e.g.,
arn:aws:iam::123456789:role/MyRole
).Use the
updateAwsIamIntegration
mutation to update your Labelbox IAM integration with the Role ARN. See a sample mutation here.Validate your integration with the
validateIamIntegration
mutation. See a sample mutation here.Create an empty dataset in Labelbox. See a sample
createDataset
mutation here.Use the
setSignerForDataset
mutation to attach the IAM integration to your dataset. See a sample mutation here.Set up CORS headers for your S3 bucket.
Create your JSON file containing your URLs and add your data to your dataset. The
validateDataset
mutation in the next step will only provide useful feedback if the dataset contains at least one data row.Use the
validateDataset
mutation to make sure the IAM integration is working properly for your dataset. This returns a payload with the status of the various checks that you can use for troubleshooting. See a sample mutation here.
Your dataset should now be set up with IAM Delegated Access. Labelbox will use the AWS role you created to generate temporary signed URLs every time it accesses data in your S3 bucket.
Create integration
Use the createAwsIamIntegration
mutation to create a Delegated Access integration between your S3 bucket and Labelbox.
Specifying the roleArn
when you are creating the integration is optional.
The id
returned from this createAwsIntegration
mutation is the Labelbox External ID. The Labelbox AWS account ID is 340636424752
.
Field | Type | Description |
---|---|---|
| String | The name of the new IAM integration. |
| String | The ARN (Amazon Resource Name) for the role created for Labelbox in your AWS account. If you do not have a role yet, you can leave out |
mutation CreateIntegration { createAwsIamIntegration(data: { name: "AWS IAM Integration" roleArn: "arn:aws:iam::<AWS_ACCOUNT_ID>:role/<ROLE_NAME>" }) { id } }
Validate integration
Use the validateIamIntegration
mutation to ensure that the integration you set up via IAM was configured properly.
Field | Type | Description |
---|---|---|
| Boolean | Indicates whether the IAM integration is valid. |
| IamIntegrationValidationCheckName | Values are |
| Boolean | Indicates whether the check was successful. |
mutation CheckIntegration { validateIamIntegration (where: {id: "<INTEGRATION_ID>"}){ valid checks { name success } } }
Update integration
Use the updateAwsIamIntegration
mutation to update the role ARN associated with the integration. Use the where
argument to specify which integration you want to update and the data
argument to specify what you want to update (i.e., roleArn
or name
).
Field | Type | Description |
---|---|---|
| String | Name of the IAM integration you want to update. |
| String | ARN of the IAM integration you want to update. |
| ID | ID for the integration you created via the |
mutation UpdateIntegration { updateAwsIamIntegration( data: { roleArn: "arn:aws:iam::<ACCOUNT_ID>:role/<ROLE_NAME>" name: "<NEW_INTEGRATION_NAME>" }, where: { id: "<INTEGRATION_ID>" }) { id } }
Attach integration to dataset
Use the setSignerForDataset
mutation to attach an IAM integration to your dataset. Use the where
argument to specify the dataset and the data
argument to specify what to change.
Field | Type | Description |
---|---|---|
| ID | The ID of an IAM integration to use as a signer for the dataset. |
| ID | Dataset ID. |
mutation SetSignerForDataset { setSignerForDataset( data: { signerId: "<INTEGRATION_ID>" }, where: { id: "<DATASET_ID>" }) { id signer { id } } }
Validate dataset
When you create your dataset via the GraphQL API, you'll need to run a dataset validation yourself. Use the validateDataset
mutation to do this.
This returns a payload with the status of the various checks that you can use for troubleshooting.
Field | Type | Description |
---|---|---|
| Boolean | Indicates whether the dataset was connected to the IAM integration successfully. |
| DatasetValidationCheckName | Values are |
| Boolean | Indicates whether the dataset validation check was successful. |
mutation ValidateDataset { validateDataset (where: {id: "<DATASET_ID>"}){ valid checks { name success } } }
Labeling parameters
In order to customize your Label queue, you need to specify the labeling parameters. For an overview of queue prioritization, see our docs on the Queue system.
Set parameter overrides
Use setLabelingParameterOverrides
to set all parameter overrides in one mutation. Then, you need to rebuild the queue. For more information on how to do this programmatically, contact our support team.
Field | Type | Description |
---|---|---|
| WhereUniqueIdInput | ID of the data row you wish to set priority for. Max number of data rows you can include is 1000. Note: |
| Int | Place in the label queue |
| Int | Number of times the asset should be labeled. This number should not exceed the number of labelers in the project. |
Returns:
Field | Type | Description |
---|---|---|
| Boolean | Returns |
mutation SetLabelingParameterOverrides { project(where: { id: "<PROJECT_ID>" }) { setLabelingParameterOverrides(data: [ { dataRow: { id: "<DATA_ROW_ID>" }, priority: 1, numLabels: 2 }, { dataRow: { id: "<DATA_ROW_ID>" }, priority: 2, numLabels: 3 } ]) { success } } }
Fetch parameter overrides
Use this query to fetch any existing labeling parameter overrides.
query PullLabelingParameters { project(where:{id:"<PROJECT_ID>"}){ labelingParameterOverrides{ id priority } } }
Unset parameter overrides
Use the unsetLabelingParameterOverrides
mutation to unset the prioritization for a set of Data Rows. Using this mutation will automatically result in the rebuild of the Label queue.
Field | Type | Description |
---|---|---|
| ID | Data rows to remove parameter overrides from. The max number of data rows you may include in this mutation is 1000. |
mutation UnsetLabelingParameterOverrides { project(where: { id: "<PROJECT_ID>" }) { unsetLabelingParameterOverrides(data: [ { dataRowId: "<DATA_ROW_ID>" }, { dataRowId: "<DATA_ROW_ID>" } ]) { success } } }
Unset all parameter overrides
Use the unsetAllLabelingParameterOverrides
to unset the labeling parameter overrides for all data rows in a project.
mutation UnsetAllParameterOverrides { project(where: {id: "<PROJECT_ID>"}) { unsetAllLabelingParameterOverrides { success deletedCount } } }
Labels
A Label is a collection of annotations on a single asset and represents an assessment on a Data Row. For a complete list of Label fields, see the Docs tab in the API explorer.
Get JSON label by ID
To get the stringified JSON value for a label, use the label
query.
query getLabelById { label(where: {id: "<LABEL_ID>"}) { label } }
Get JSON label by project
Use this query to get a JSON label by project ID.
Argument | Type | Description |
---|---|---|
| PageSize | Number of elements in the paginated result |
| Int | Number of labeled assets from the project to skip |
query getLabelsFromProject { projects (where: {id: "<PROJECT_ID>"}) { id name labels (first: 10) { id createdBy { email } label } } }
Individual export
Use this query to export individual labels or a subset of labels.
Argument | Type | Description |
---|---|---|
| PageSize | Number of elements in the paginated result |
| Int | Number of labeled assets from the project to skip |
query APIGetPageOfLabels { project (where:{id: "<PROJECT_ID>"}) { labels (first: 5){ id label createdBy { id email } type { id name } secondsToLabel agreement dataRow { id rowData } } } }
Bulk export
Use the exportLabels
mutation to bulk export labels from your project.
Running this mutation should return:
Field | Type | Description |
---|---|---|
| String | URL to the JSON file containing the labels for the project. This mutation will generate a new |
| String | Timestamp indicating when the export was generated |
| Boolean | If |
mutation BulkExportLabels { exportLabels (data:{ projectId: "<PROJECT_ID>" }){ downloadUrl createdAt shouldPoll } }
Delete labels
When you delete a label, the asset is automatically re-enqueued, meaning it is re-entered into the labeling queue. Please see our docs on relabeling data to read about re-enqueuing labels.
mutation DeleteLabels { deleteLabels ( labelIds:["LABEL_ID>"] ){ id deleted } }
Keep deleted labels as templates
Use the bulkDeleteLabels
mutation to keep deleted labels as templates.
Caution
When you delete a label but keep it as a template, the labeling time and any other metrics are not preserved, only the label itself.
Field | Type | Definition |
---|---|---|
| Boolean | Must be set to |
mutation BulkDeleteLabels ( $projectId: ID!, $makeTemplates: Boolean = true, $labelsWhere: WhereBulkLabelDelete, $first: PageSize, $skip: Int ) { project (where: {id: $projectId}) { bulkDeleteLabels ( where: $labelsWhere, makeTemplates: $makeTemplates, waitForQueue: true, first: $first, skip: $skip ) { count } } }
Members
A member is an individual user in your organization. Members have permissions that can be configured at the organization-level or the project-level. Use the roles
query to get the id
for each role.
Add members at project-level
Use the addUserToProject
mutation to add a member to a project and select their role.
Field | Type | Description |
---|---|---|
| String | User email |
| String | ID of the project to add the member to |
| String | Admin: Team manager: Project-based: Reviewer: Labeler: |
mutation AddUserToProject { addUserToProject ( data: { email: "<USER_EMAIL>", projectId: "<PROJECT_ID>", roleId: "<ROLE-ID>" } ) { user { email } project { name } role { name } } }
Add members to an organization
Use the addMembersToOrganization
mutation to add members and set their role at the organization-level.
Field | Type | Description |
---|---|---|
| String | Team member email |
| ID | Organization role |
| ID | Leave empty |
This sample mutation adds two new members as Admin at the Organization level.
mutation MakeNewUserAdmin { addMembersToOrganization( data: { emails: ["sample1@email.com", "sample2@email.com"], orgRoleId: "cjlvi91a41aab0714677xp87h", projectRoles: [] } ) { newUserId existingUserEmail existingUserInviteSent } }
Get available roles
Use the roles
query to get the IDs for all of the member roles. Use the first
argument to specify how many objects to return and the skip
argument to specify how many objects to skip.
Field | Type | Definition |
---|---|---|
| String | Role name |
| ID | Role ID |
| PermissionFlag | All available permissions for that role |
query GetAvailableRoles { roles ( first: 10 skip: 1 ){ name id permissions } }
List member projects
Use the users
query to get a list of all the projects a member is associated with.
query getUserProjects { users ( where: {email:"<USER-EMAIL>"}) { id projects { name id } } }
Remove members
Use this setProjectMembership
mutation to remove project-based members.
Field | Type | Description |
---|---|---|
| ID | Member ID |
| ID | Set |
| ID | Project ID |
mutation RemoveMemberFromProject { setProjectMembership (data: { userId:"<USER_ID>" roleId: "cjmb6xy80f5vz0780u3mw2rj4" projectId:"<PROJECT_ID>" }) { id } }
Ontologies
An Ontology contains all of the classes used for labeling assets in a Project.
For a complete list of fields for Ontology, see the Docs tab in the API explorer.
Get an ontology
Use this GraphQL query to get an existing ontology for a project.
query getOntology { project (where: {id: "<PROJECT_ID>"}) { ontology { normalized } } }
Clone an ontology
A cloned ontology is a copy of an existing ontology. Any changes made to the ontology will not affect the ontology it was cloned from. Note: Cloning ontologies from the legacy editor to the new editor is not supported.
Use the cloneOntology
mutation to target the ontology by id
and clone it.
mutation cloneOntologyFromProject { project (where: {id: "<PROJECT_ID>"}) { cloneOntology (ontologyId: "<TARGET_ONTOLOGY_ID>"){ id name } } }
Connect an ontology
Connecting an existing ontology is useful if you have multiple projects that must reference the same exact ontology. Any changes made to an ontology will affect all projects sharing that ontology. Note: Connecting ontologies from the legacy editor to the new editor is not supported.
Use the connectableOntologies
query to list all ontologies that can be shared with a given project.
Then, use the project
mutation to connect that ontology to your project.
query connectableOntologies { project(where: { id: "<PROJECT_ID>" }) { connectableOntologies { id name } } }
mutation connectOntologyToProject { project(where: {id: "<PROJECT_ID>"}) { connectOntology(ontologyId: "<TARGET_ONTOLOGY_ID>"){ id name } } }
Rename an ontology
Use the ontology
mutation to rename an ontology.
mutation RenameOntology { ontology(where: { id: "<PROJECT_ID>" }) { update(data: { name: "<NEW_NAME>" }) { id name } } }
Projects
Create a project
Use this mutation to create a project.
mutation { createProject(data:{ name: "<PROJECT_NAME>" }){ id } }
Review
A Review is an assessment of a Label by a human reviewer.
Enable review step
Use the upsertReviewQueue
mutation to enable the review step for a project and specify the percentage of assets that should be reviewed.
Field | Type | Description |
---|---|---|
quotaFactor | Float | A value between 0 and 1 that represents the percentage of asset from the project to review. |
mutation UpsertReviewQueue( $projectId: ID!, $quotaFactor: Float!) { upsertReviewQueue(where: { project: { id: $projectId } }, data: {quotaFactor: $quotaFactor}) { id } }
Disable review step
Use the deleteReviewQueue
mutation to disable the review step for a specific project.
mutation DeleteReviewQueue($projectId: ID!) { deleteReviewQueue(where: { project: { id: $projectId } }) { id } }
Webhooks
Use webhooks to set up a workflow to receive automatic notifications when an event happens in Labelbox. For a tutorial on setting up a simple webhooks workflow, see Webhooks setup.
Create a webhook
Use the createWebhook
mutation to create a webhook for a project.
Field | Type | Description |
---|---|---|
| ID | Project ID |
| String | URL where Labelbox server should send notifications |
| String | User-generated secret used for verification |
| WebhookTopic | Values are:
|
mutation CreateWebhook { createWebhook(data:{ project:{ id:"<PROJECT_ID>" }, url:"<HTTP_URL>", secret:"example_secret", topics:{ set:[ LABEL_CREATED, LABEL_UPDATED, LABEL_DELETED ] } }){ id } }
Update a webhook
After verifying and when entering production, use the updateWebhook
mutation to update a specific webhook.
mutation UpdateWebhook { updateWebhook(where:{ id:"<WEBHOOK_ID>" }, data:{ url:"<PRODUCTION_URL>" }){ id } }
Remove a webhook
Use the updateWebhook
mutation to set the webhook status to INACTIVE
.
Field | Type | Definition |
---|---|---|
| WebhookStatus | Values are: |
mutation RemoveWebhook { updateWebhook( data:{ status: INACTIVE } where:{ id:"<WEBHOOK_ID>" } ){ id } }