--- title: "Public API" canonical: "https://help.starhive.com/space/DOC/21856258/Public%20API" format: markdown --- > Macro (toc) ## About Starhive offers a public API to enable you to integrate from other applications. The API is accessible under `https://api.starhive.com/public/v1` ## Authentication To authenticate with the API you will need to have a *personal access token *(PAT). Read more about it [here](https://help.starhive.com/space/DOC/205914114/Personal+Access+Token). ## Workspace header The choice of workspace to query data from is determined by the request header called `starhive-workspace-id`. The header is mandatory and must be applied to all API calls (except for the endpoint to fetch the workspaces). The curl command below appends the header for an example workspace. ``` curl --header 'starhive-workspace-id: 3a6de57d-ea5e-4e1d-ba1c-6e427e282e79' ``` In order to find the workspace id a user needs to fetch the workspace info using the workspace endpoint ``` GET https://api.starhive.com/public/v1/workspace ``` ## Pagination The Starhive API uses pagination for results that might include a large set of data. The Starhive pagination works the same way for all API endpoints that returns a list of data. All API endpoints that have pagination support will use the Starhive default page size if the pagination query parameters are omitted. - offset - how many entires should be removed from the start of the result. When paginating through a complete set the next limit as `previous limit + size` - limit - how many entries should be in included in every result The pagination response shape has 3 fields - total - the count of all entities that match the query - pageSize - the page size that was requested as the limit parameter - isLast - indicates that the result is the last for the given query - result - the array of all items for the current page. When the number of entries in the result is less than size there are no more results to fetch. ```json { "total": 100, "pageSize": 10, "isLast": true "result": [ ... ] } ``` ## Rate limits Starhive applies rate limits to tokens and workspaces. There will be one limit that is applied to each and every token and another one that will be applied to the workspace. In other words two tokens used to send requests to the same workspace will count towards the token rate limit and both will count towards the workspace limit. When the limit is reached the endpoint will respond with an HTTP response code of `429` and the client need to reduce the amount of requests. - A user can make up to 1000 request in a 5 min window - A workspace can make up to 10 000 requests in a 5 min window ## Common error responses ### Bad request HTTP status `400` #### Invalid request When an invalid json is sent as a request the common response shape will be together with the HTTP response code of `400`. The message in the below example is sometimes omitted. ```json { "timestamp": "2023-12-05T12:49:39.304614Z", "message": "Provided StarQL query is invalid" "path": "/public/v1/object/search" } ``` #### Validation error In the API endpoints that creates or modifies data the common bad request will return the common response shape that contains a list of violations, a message, a path and a timestamp. The list of violations will contain the error domain as well as the error code in the violationType. Each domain have a limited set of violationType, see respective endpoint for details. ```json { "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 status `429` - See rate Rate Limit for explanation. ## Common flows ### Attribute Creating an attribute can be done with the public API. An example payload when creating an attribute with default configuration looks like this (note the omitted configuration which will fall back to the default configuration for the attribute type): ``` { "name": "The attribute name", "description": "A descripton", "typeId": "9d8672de-6652-4555-8f54-b0032e83001f" "attributeTypeCode": "TEXT", "configuration":null, "isLabel": false } ``` Attribute type codes can be fetched using the Attribute Type API. The configuration structure varies depending on the attribute type. To see all the different configurations [read this](https://help.starhive.com/space/DOC/177340428/Attribute). Example of payloads for the different configurations can be found in [swagger](https://api.starhive.com/openapi/starhive-public-api.html).** Note that the configuration must match what is supported by the attribute type. ** #### Attribute PATCH When using the PATCH endpoint for attributes, you can perform partial updates on the attribute fields. However, if your update involves the configuration, you **must provide both the **`attributeTypeCode`** and the complete configuration object**. - **Partial updates within configuration:** If you only want to update certain fields within the configuration, you **still need to include the entire configuration object**, with both the old values (for fields you want to retain) and the new values (for fields you want to change). The configuration fields that is left out from the payload will bee **overwritten with it's default value**. ### Object creation An example object creation payload looks like ```json { "typeId": "9d8672de-6652-4555-8f54-b0032e83001f", "attributes": [ { "attributeId": "c6265c66-ec27-4b2f-8ee1-7255101dba2a", "values": [ "Object Name" ] } ] } ``` which will create an object in the Type identified by `typeId` and assign the "Object Name" value to the attribute identified by the `attributeId` property. In order to retrieve the identifiers required use the `/public/v1/type/enriched` endpoint to retrieve all Types together with their attributes. ### Media attributes In order to add attribute values to attributes of type Media one has to first get a pre-signed URL to upload the actual file. Ones the file is uploaded the key of the uploaded file will be used to associate it with an object. #### Add Media Attribute Value Flow ##### 1. Get a pre-signed URL ``` POST https://api.starhive.com/public/v1/content { "fileName": "webp.webp", "fileSize": 94764, "contentType": "image/webp" } ``` The fileName, fileSize and contentType will be validated on upload so it is important that they match the file to be uploaded. The response for the above example will be ```json { "presignedUrl": "https://starhive...?X-Amz-Security-Token=...", "contentKey": "temp/3f6de57d-ea5e-4e1d-aa1c-6e427e282e79/05097650-29da-42d6-b8b9-8809bf351423" } ``` ##### 2. Upload the file Use the payload from the previous step to upload the file. The URL where to upload the file is present in property keyed by `presignedUrl` . Do not tamper with this URL as it will fail the upload. ```shell 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 'UklGRiRyAQBXRUJQVlA4TBdyAQAvFsJRAI0wjiQpCLv6myH/gEEwhIj+TwAgglvQhHsB1TkVSLwQ8JyEe686aDt64PFc3rfbdAtzHqAQBm3HaMfO7VzcvG/' ``` ##### 3. Associate the file with the object Use the `contentKey` as retrieved in step 1 as the value to update the object attribute of type media with. ```shell 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. When the `temp/..` key has been used it can not be re-used for the same or another object again. Instead all the above steps need to be done in sequence again. ### Workflow attributes #### Find out possible state ids for workflow attribute For attribute values of type Workflow it’s required to provide the id of the desired state. The workflow id is available in the attribute response, for example: ``` curl -X GET --location "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" ``` Response: ``` { "id": "9955afb1-62f9-464e-8c21-67f7827827aa", "typeId": "ebed26e4-d518-42e0-bb29-e6e0ba2f307e", "attributeTypeId": "569e2f84-f225-4494-86b5-d71cbfd5823b", "name": "Status", "isLabel": false, "isIndestructible": false, "configuration": { "workflow": { "id": "31e317dd-7b45-416d-af67-3c3aaffcfbdc" } } } ```   Knowing the workflow id it’s possible to traverse the states and transitions by using `available-transitions` endpoint. The parameter `fromStateId` can be omitted to see possible transitions from the empty state. ``` curl -X GET --location "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" ``` Response: ``` { "transitions": [ { "id": "775d13be-8b36-421e-9978-a777352603da", "name": "start working", "isFromEmptyState": false, "fromStateId": "30f66d59-5fea-43af-a731-6d41cde8984c", "toStateId": "a80b65f6-93f0-40cd-986f-552d1e2045a7" } ] } ``` #### Provide transitionId when creating or updating object Updating an attribute value of workflow type implies that a transition happens from the previous (or empty if the attribute value didn’t exist before) state to the desired state. If there’s only one transition defined from the previous to the desired state, it is detected automatically and no additional data is required from the user to update the corresponding attribute value. If there are multiple transitions from the previous state to the desired state, trying to create/update an object would result in the following error: ``` { "violations": [ { "fieldIdentifier": "9955afb1-62f9-464e-8c21-67f7827827aa", "domain": "ATTRIBUTE", "violationType": "AMBIGUOUS_TRANSITION", "invalidValue": "5a7ab649-e1b9-43cd-8cc4-fcd921739604" } ], } ```   In this case it is required to provide the transition id explicitly. For example patching an object: ``` curl -X PATCH --location "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 Sometimes you might need to get a hold of users list in order to set it in a User attribute value or mention a user in Rich Text attribute value. In order to do so you can use users list api endpoint `https://api.starhive.com/public/v1/user` or get user details by id bycalling `https://api.starhive.com/public/v1/user/{id}` #### User mentions To mention user in Rich Text attribute value use the following syntax (replace USER_ID with the actual user id): ``` Hi {{@userId:$USER_ID}} ``` ## API documentation ### Swagger documentation Only the `/public/**` API endpoints accept the User Access Token. Other API endpoints will reject with an Unautorized response code if they are attempted. #### Swagger UI [https://api.starhive.com/openapi/starhive-public-api.html](https://api.starhive.com/openapi/starhive-public-api.html)