Skip to main content

Public API

About​

Starhive provides a public API for integration with external applications. The API endpoint is https://api.starhive.com/public/v1.

Authentication​

Authentication requires a personal access token (PAT). Refer to the Personal Access Token documentation for setup details.

Workspace header​

All API requests (except workspace fetching) must include the starhive-workspace-id header to specify the target workspace:

curl --header 'starhive-workspace-id: 3a6de57d-ea5e-4e1d-ba1c-6e427e282e79'

Retrieve your workspace ID using:

GET https://api.starhive.com/public/v1/workspace

Pagination​

List endpoints support pagination via query parameters:

  • offset — number of entries to skip from the start
  • limit — number of entries per page

The response structure includes:

  • total — count of matching entities
  • pageSize — requested page size
  • isLast — whether this is the final page
  • result — array of items for the current page
{
  "total": 100,
  "pageSize": 10,
  "isLast": true,
  "result": []
}

Rate limits​

Rate limits apply per token and per workspace:

  • Per token: up to 1000 requests in a 5-minute window
  • Per workspace: up to 10,000 requests in a 5-minute window

Exceeded limits return HTTP 429; clients must reduce request frequency.

Common error responses​

Bad request (HTTP 400)​

Invalid JSON returns:

{
  "timestamp": "2023-12-05T12:49:39.304614Z",
  "message": "Provided StarQL query is invalid",
  "path": "/public/v1/object/search"
}

Validation errors for create/modify operations include violation details:

{
  "violations": [
    {
      "fieldIdentifier": "name",
      "violationType": "CONFLICT",
      "invalidValue": "Input value",
      "domain": "TYPE"
    }
  ],
  "message": "Bad request",
  "path": "/public/v1/type",
  "timestamp": "2023-12-06T15:27:34.018801Z"
}

Too many requests (HTTP 429)​

Triggered by rate limit violations.

Common flows​

Attribute creation​

Example payload for creating an attribute:

{
  "name": "The attribute name",
  "description": "A description",
  "typeId": "9d8672de-6652-4555-8f54-b0032e83001f",
  "attributeTypeCode": "TEXT",
  "configuration": null,
  "isLabel": false
}

Fetch attribute type codes from the Attribute Type API. Configuration structures vary by attribute type.

Attribute PATCH operations​

Partial updates are supported, but if your update involves the configuration, you must provide both the attributeTypeCode and the complete configuration object. Fields omitted from the configuration revert to defaults.

Object creation​

Example object creation payload:

{
  "typeId": "9d8672de-6652-4555-8f54-b0032e83001f",
  "attributes": [
    {
      "attributeId": "c6265c66-ec27-4b2f-8ee1-7255101dba2a",
      "values": ["Object Name"]
    }
  ]
}

Use /public/v1/type/enriched to retrieve type and attribute identifiers.

Media attributes​

A three-step process for adding media:

1. Get a pre-signed URL:

POST https://api.starhive.com/public/v1/content
{
  "fileName": "webp.webp",
  "fileSize": 94764,
  "contentType": "image/webp"
}

Response:

{
  "presignedUrl": "https://starhive...?X-Amz-Security-Token=...",
  "contentKey": "temp/3f6de57d-ea5e-4e1d-aa1c-6e427e282e79/05097650-29da-42d6-b8b9-8809bf351423"
}

2. Upload the file:

curl --request PUT \
  --url 'https://starhive...?X-Amz-Security-Token=...' \
  --header 'Content-Disposition: attachment; filename=webp.webp' \
  --header 'Content-Length: 94764' \
  --header 'Content-Type: image/webp' \
  --data '[file data]'

3. Associate with the object:

curl --request PATCH \
  --url https://api.starhive.com/public/v1/object/1a22a390-a10c-4d81-a390-99f3280e9ad5 \
  --header 'Authorization: Bearer sp_' \
  --header 'Content-Type: application/json' \
  --header 'starhive-workspace-id: 3f6de57d-ea5e-4e1d-aa1c-6e427e282e79' \
  --data '{
    "attributes": [{
      "attributeId": "5662aace-d920-4db9-9078-0a61362c58b8",
      "values": ["temp/3f6de57d-ea5e-4e1d-aa1c-6e427e282e79/05097650-29da-42d6-b8b9-8809bf351423"]
    }]
  }'

The contentKey for a pre-signed URL is only valid once. After use, repeat all steps for subsequent uploads.

Workflow attributes​

Find possible state IDs: retrieve the attribute to get the workflow ID:

curl -X GET "https://api.starhive.com/public/v1/attribute/9955afb1-62f9-464e-8c21-67f7827827aa" \
  -H "Authorization: Bearer sp_" \
  -H "starhive-workspace-id: 3f6de57d-ea5e-4e1d-aa1c-6e427e282e79"

The response includes the workflow configuration with its ID.

Available transitions:

curl -X GET "https://api.starhive.com/public/v1/workflow/31e317dd-7b45-416d-af67-3c3aaffcfbdc/available-transitions?fromStateId=30f66d59-5fea-43af-a731-6d41cde8984c" \
  -H "Authorization: Bearer sp_" \
  -H "starhive-workspace-id: 3f6de57d-ea5e-4e1d-aa1c-6e427e282e79"

Omit fromStateId to see transitions from the initial state.

Multiple transitions: if more than one transition exists to the target state, explicitly provide the transition ID:

curl -X PATCH "https://api.starhive.com/public/v1/object/a63b8d1a-5477-4a76-9c50-2d5d6c96ad4e" \
  -H "Authorization: Bearer sp_" \
  -H "starhive-workspace-id: 3f6de57d-ea5e-4e1d-aa1c-6e427e282e79" \
  -H "Content-Type: application/json" \
  -d '{
    "attributes": [{
      "attributeId": "9955afb1-62f9-464e-8c21-67f7827827aa",
      "values": ["5a7ab649-e1b9-43cd-8cc4-fcd921739604"]
    }],
    "transitions": {
      "9955afb1-62f9-464e-8c21-67f7827827aa": {
        "transitionId": "d5ab35c1-b13c-4640-9c84-ff08e2cd8b30"
      }
    }
  }'

Users​

Retrieve user lists for User attribute values or Rich Text mentions using:

  • https://api.starhive.com/public/v1/user
  • https://api.starhive.com/public/v1/user/{id}

User mentions syntax:

Hi {{@userId:$USER_ID}}

Replace USER_ID with the actual user ID.

API documentation​

Access the full API specification (Swagger UI) at https://api.starhive.com/openapi/starhive-public-api.html.

Only /public/** endpoints accept User Access Tokens; other endpoints return 401 Unauthorized.