Jebbit
API docs by Redocly

Jebbit API (v1)

Download OpenAPI specification:

URL: https://www.jebbit.com

Use the Jebbit API to automate tasks relating to your Businesses, Campaigns, Product Feeds, Launch Links, and Integrations. All requests and responses follow the JSON:API specification using the application/vnd.api+json content type.

Authentication Guide

Use the client_id and client_secret provided by Jebbit in the Auth endpoint to generate an access_token. This token is a JSON Web Token (JWT) and is valid for 24 hours. After expiry you must request a new one.

Include the token in every API request via the Authorization header:

Authorization: Bearer <your access_token here>

Multi-business tokens: If your access_token has scopes for multiple businesses, you must send an x-jebbit-business header with every request. The value is the target business ID — this sets the scope of the request.

API Resource Sorting

All resources are returned in descending order by creation time (newest first).

Pagination

By default every collection endpoint returns all of the records your business owns in a single response, and that remains the behaviour when no page parameters are sent — existing integrations do not need to change.

Where an endpoint supports paging, send page[number] (counting from 1) and page[size] to request a slice instead. page[size] may not exceed 1000. GET /api/v1/campaigns and GET /api/v1/campaign_stats support paging today; the remaining collections are small enough that they always return whole.

GET /api/v1/campaigns additionally supports filter[launched] and filter[title_contains], which is usually a better way to find what you need than paging through the account.

Rate Limiting

API requests are subject to rate limiting. Contact Jebbit support for your plan's limits.

Integration / Webhook Client Guide

When using the Integrations endpoint to receive Jebbit webhooks, keep the following in mind. We also provide an Example Webhook Client Repo as a quickstart.

Test Webhooks

You can send a test webhook to your endpoint to verify connectivity and the signature verification flow before going live.

Important: Jebbit sends an x-jebbit-test header with every test webhook. Your application should discard these and not process them through your data ingestion pipeline.

Verifying Webhook Signatures

Every webhook includes an x-jebbit-signature header so you can verify it originated from Jebbit. The signature has the format:

x-jebbit-signature: t=<timestamp>,v1=<hmac>

Step 1 — Validate the timestamp. Ensure the timestamp is within a reasonable threshold (e.g., 5 minutes) of the current time to guard against replay attacks:

if timestamp < Time.now.to_i - 300
  raise StandardError, 'Timestamp outside of tolerance'
end

Step 2 — Verify the HMAC. Reconstruct the signed payload and compare:

generated_payload = "#{timestamp}.#{request.body}"

calculated_hmac = Base64.strict_encode64(
  OpenSSL::HMAC.digest('sha256', shared_secret, generated_payload)
)

ActiveSupport::SecurityUtils.secure_compare(hmac, calculated_hmac)

If the HMACs match, accept the payload as valid and continue processing.

Authentication

Authenticate with the API and obtain access tokens.

Request an access token

Exchange your API credentials for a JWT bearer token. The returned token must be included in the Authorization header of all subsequent requests. Tokens are scoped to the business associated with the given credentials.

Request Body schema: application/vnd.api+json
required

API credentials to authenticate with.

client_id
required
string

Your API client identifier, found in the Jebbit dashboard under API settings.

client_secret
required
string

Your API client secret. Keep this value confidential.

Responses

Request samples

Content type
application/vnd.api+json
{
  • "client_id": "aBcDeFgHiJkLmNoPqRsT",
  • "client_secret": "s3cr3t-k3y-v4lu3"
}

Response samples

Content type
application/vnd.api+json
{
  • "data": {
    }
}

Business Account

Retrieve information about the authenticated business account.

Get current business

Returns the business account associated with the authenticated API token. Use this endpoint to verify your credentials and retrieve your business ID.

Authorizations:
JWT

Responses

Response samples

Content type
application/vnd.api+json
{
  • "data": {
    }
}

Campaigns

List and retrieve marketing campaigns and their metadata.

List all campaigns

Returns all campaigns belonging to the authenticated business. Each campaign includes its title, launch date, and active iteration.

Authorizations:
JWT
query Parameters
filter[launched]
boolean
Example: filter[launched]=true

true returns only campaigns that have been launched, false only those never launched. Omit for both. Accepts true/false or 1/0; any other value is rejected with a 400 rather than guessed at.

filter[title_contains]
string
Example: filter[title_contains]=Product Quiz

Return only campaigns whose title contains this string, case-insensitive. LIKE wildcards (%, _) in the value are matched as literal characters.

page[number]
integer >= 1
Example: page[number]=2

Which page to return, counting from 1. Omit both page parameters to receive the whole collection in one response, which is the default behaviour.

page[size]
integer [ 1 .. 1000 ]
Example: page[size]=100

How many records per page. Omit both page parameters to receive the whole collection in one response, which is the default behaviour.

Responses

Request samples 

curl https://api2.jebbit.com/api/v1/campaigns \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/vnd.api+json"

Response samples

Content type
application/vnd.api+json
Example
{
  • "data": [
    ]
}

Get a campaign

Returns a single campaign by its public ID, including its title, launch date, and the identifier for its currently active iteration.

Authorizations:
JWT
path Parameters
campaign_id
required
string
Example: def567

The public ID of the campaign to retrieve.

Responses

Response samples

Content type
application/vnd.api+json
{
  • "data": {
    }
}

Campaign Stats

Campaign performance for a date range, including the recommendation distribution and per-question drop-off.

List campaign performance

Returns performance totals for every campaign in the brand. Campaigns with no activity in the range report zeros rather than being omitted, so the response shape is stable.

The per-outcome and per-question breakdowns are not included here - request a single campaign to get those. They are the expensive half of the resource and do not aggregate into anything useful across an account, so a brand with thousands of campaigns would pay for detail no caller can read. Use this endpoint to find the campaign worth looking at, then GET /api/v1/campaign_stats/{campaign_id} for what happened inside it.

Authorizations:
JWT
query Parameters
filter[start_date]
string <date>
Example: filter[start_date]=2024-06-01

Only count activity on or after this ISO 8601 date (YYYY-MM-DD).

filter[end_date]
string <date>
Example: filter[end_date]=2024-06-30

Only count activity on or before this ISO 8601 date (YYYY-MM-DD).

page[number]
integer >= 1
Example: page[number]=2

Which page to return, counting from 1. Omit both page parameters to receive the whole collection in one response, which is the default behaviour.

page[size]
integer [ 1 .. 1000 ]
Example: page[size]=100

How many records per page. Omit both page parameters to receive the whole collection in one response, which is the default behaviour.

Responses

Response samples

Content type
application/vnd.api+json
{
  • "data": [
    ],
  • "meta": {
    }
}

Get performance for one campaign

Returns performance for a single campaign, including which recommendations respondents were shown and where they dropped off question by question. This is the only endpoint that returns those breakdowns; the collection endpoint reports totals only.

Authorizations:
JWT
path Parameters
campaign_id
required
string
Example: abc123

The public ID of the campaign.

query Parameters
filter[start_date]
string <date>
Example: filter[start_date]=2024-06-01

Only count activity on or after this ISO 8601 date (YYYY-MM-DD).

filter[end_date]
string <date>
Example: filter[end_date]=2024-06-30

Only count activity on or before this ISO 8601 date (YYYY-MM-DD).

Responses

Response samples

Content type
application/vnd.api+json
{
  • "data": {
    }
}

Integrations

List every integration configured for the brand, across all services, and see how each one maps and transforms campaign data on its way out.

List the brand's integrations

Returns every integration configured for the brand, across all services, with its destination, field mappings and injected static values. Read-only. Includes integrations provisioned outside the Jebbit dashboard, marked by dashboard_managed - those still receive data. For creating and managing webhook subscriptions, see /api/v1/webhook_integrations.

Authorizations:
JWT

Responses

Response samples

Content type
application/vnd.api+json
{
  • "data": [
    ],
  • "meta": {
    }
}

Get one integration

Returns a single integration by its public ID.

Authorizations:
JWT
path Parameters
integration_id
required
string
Example: abc123

The public ID of the integration.

Responses

Response samples

Content type
application/vnd.api+json
{
  • "data": {
    }
}

List campaigns linked to an integration

Returns the campaigns explicitly linked to this integration. A brand-attached integration also fires for every other campaign in the account without appearing here - the integration's own attached_at field is what tells you that. Requires read:campaign, since the response contains campaigns.

Authorizations:
JWT
path Parameters
integration_id
required
string
Example: abc123

The public ID of the integration.

Responses

Response samples

Content type
application/vnd.api+json
{
  • "data": [
    ],
  • "meta": {
    }
}

List integrations for a campaign

Returns the integrations explicitly linked to this campaign. Brand-attached integrations apply to every campaign and are not returned here - the campaign's integration_counts reports them as inherited. Static values on this route resolve with the campaign level included. Requires read:integration, since the response contains integrations.

Authorizations:
JWT
path Parameters
campaign_id
required
string
Example: abc123

The public ID of the campaign.

Responses

Response samples

Content type
application/vnd.api+json
{
  • "data": [
    ],
  • "meta": {
    }
}

Webhook Integrations

Create, update and test webhook subscriptions. The only endpoints that return a credential (shared_secret), which you use to verify the signature on delivered payloads.

List all integrations

Returns all integrations configured for the authenticated business. Integrations define how and where Jebbit sends submission data (e.g., webhooks, CRM connectors).

Authorizations:
JWT

Responses

Response samples

Content type
application/vnd.api+json
Example
{
  • "data": [
    ]
}

Create an integration

Creates a new integration for the authenticated business. Specify the endpoint URL, region, and any additional delivery options. The integration will begin receiving data once campaigns are configured to use it.

Authorizations:
JWT
Request Body schema: application/vnd.api+json
required

Integration configuration to create.

object

Responses

Request samples

Content type
application/vnd.api+json
{}

Response samples

Content type
application/vnd.api+json
{
  • "data": {
    }
}

Get an integration

Returns a single integration by its public ID, including its endpoint, service type, region, and configuration details.

Authorizations:
JWT
path Parameters
webhook_integration_id
required
string
Example: abc123

The public ID of the integration to retrieve.

Responses

Response samples

Content type
application/vnd.api+json
{
  • "data": {
    }
}

Update an integration

Updates an existing integration's configuration. Only the provided attributes are modified; omitted attributes retain their current values.

Authorizations:
JWT
path Parameters
webhook_integration_id
required
string
Example: abc123

The public ID of the integration to update.

Request Body schema: application/vnd.api+json
required

Attributes to update on the integration. Only include fields you want to change.

object

Responses

Request samples

Content type
application/vnd.api+json
{}

Response samples

Content type
application/vnd.api+json
{
  • "data": {
    }
}

Delete an integration

Permanently deletes an integration and stops all future data deliveries to its endpoint. This action cannot be undone.

Authorizations:
JWT
path Parameters
webhook_integration_id
required
string
Example: abc123

The public ID of the integration to delete.

Responses

Response samples

Content type
application/vnd.api+json
{
  • "errors": [
    ]
}

Send a test submission

Sends a test payload to the integration's configured endpoint. Use this to verify connectivity and payload format before going live. The test submission contains sample data and does not affect production records.

Authorizations:
JWT
path Parameters
webhook_integration_id
required
string
Example: abc123

The public ID of the integration to test.

Responses

Response samples

Content type
application/vnd.api+json
{
  • "data": {
    }
}

Variable Mappings

Map Jebbit data variables to fields in external systems.

List all integration mappings

Returns all variable mappings across all integrations for the authenticated business. Each mapping defines how a Jebbit variable (e.g., an outcome or attribute) is mapped to a field in the external system.

Authorizations:
JWT

Responses

Response samples

Content type
application/vnd.api+json
Example
{
  • "data": [
    ]
}

Create an integration mapping

Creates a new variable mapping for an integration. The mapping defines which Jebbit variable (jebbit_var) corresponds to which field in the external system (client_var). The reserved value $metadata cannot be used as a jebbit_var.

Authorizations:
JWT
Request Body schema: application/vnd.api+json
required

The mapping to create, linking a Jebbit variable to an external field.

object

Responses

Request samples

Content type
application/vnd.api+json
{
  • "data": {
    }
}

Response samples

Content type
application/vnd.api+json
{
  • "data": {
    }
}

Get an integration mapping

Returns a single integration mapping by its public ID, including the Jebbit variable, external field, and default value.

Authorizations:
JWT
path Parameters
integration_mapping_id
required
string
Example: abc123

The public ID of the integration mapping to retrieve.

Responses

Response samples

Content type
application/vnd.api+json
{
  • "data": {
    }
}

Update an integration mapping

Updates an existing integration mapping. Only the provided attributes are modified; omitted attributes retain their current values.

Authorizations:
JWT
path Parameters
integration_mapping_id
required
string
Example: abc123

The public ID of the integration mapping to update.

Request Body schema: application/vnd.api+json
required

Attributes to update on the mapping. Only include fields you want to change.

object

Responses

Request samples

Content type
application/vnd.api+json
{
  • "data": {
    }
}

Response samples

Content type
application/vnd.api+json
{
  • "data": {
    }
}

Delete an integration mapping

Permanently deletes an integration mapping. Future submissions will no longer include this variable in payloads sent to the integration.

Authorizations:
JWT
path Parameters
integration_mapping_id
required
string
Example: abc123

The public ID of the integration mapping to delete.

Responses

Response samples

Content type
application/vnd.api+json
{
  • "errors": [
    ]
}

Historic Backfills

Trigger and monitor historic data backfills for integrations.

List all historic backfills

Returns all historic backfill jobs for the authenticated business. A backfill replays past submission data through an integration, useful when configuring a new integration for existing campaigns.

Authorizations:
JWT

Responses

Response samples

Content type
application/vnd.api+json
Example
{
  • "data": [
    ]
}

Create a historic backfill

Triggers a new historic backfill job for an integration. This replays all past submission data through the specified integration. The integration must be active; backfills cannot be created for inactive integrations.

Authorizations:
JWT
Request Body schema: application/vnd.api+json
required

Specify which integration to run the historic backfill for.

object

Responses

Request samples

Content type
application/vnd.api+json
{
  • "data": {
    }
}

Response samples

Content type
application/vnd.api+json
{
  • "data": {
    }
}

Get a historic backfill

Returns a single historic backfill job by its public ID, including its current status (received, processing, completed, or failed).

Authorizations:
JWT
path Parameters
backfill_id
required
string
Example: abc123

The public ID of the backfill job to retrieve.

Responses

Response samples

Content type
application/vnd.api+json
{
  • "data": {
    }
}

Restart a historic backfill

Restarts a previously completed or failed backfill job. A backfill that is currently processing cannot be restarted — wait for it to complete or fail first.

Authorizations:
JWT
path Parameters
backfill_id
required
string
Example: abc123

The public ID of the backfill job to restart.

Request Body schema: application/vnd.api+json

Empty request body — send an empty JSON:API object to trigger the restart.

object

Responses

Request samples

Content type
application/vnd.api+json
{ }

Response samples

Content type
application/vnd.api+json
{
  • "data": {
    }
}

Scheduled Exports

Scheduled exports of session data to SFTP, cloud storage or email, with their cadence, field selection and recent run history.

List scheduled exports

Returns every scheduled export configured for the brand - cadence, format, field selection, destination and the last ten runs, so you can see whether an export is still working. Credentials are never returned.

Authorizations:
JWT

Responses

Response samples

Content type
application/vnd.api+json
{
  • "data": [
    ],
  • "meta": {
    }
}

Get one scheduled export

Returns a single scheduled export by its public ID.

Authorizations:
JWT
path Parameters
uploader_id
required
string
Example: upl123

The public ID of the uploader.

Responses

Response samples

Content type
application/vnd.api+json
{
  • "data": {
    }
}

List campaigns linked to a scheduled export

Returns the campaigns explicitly linked to this uploader. A brand-attached uploader also covers every other campaign in the account without appearing here - its attached_at field is what tells you that. Requires read:campaign.

Authorizations:
JWT
path Parameters
uploader_id
required
string
Example: upl123

The public ID of the uploader.

Responses

Response samples

Content type
application/vnd.api+json
{
  • "data": [
    ],
  • "meta": {
    }
}

List scheduled exports for a campaign

Returns the scheduled exports explicitly linked to this campaign. Brand-attached uploaders cover every campaign and are not returned here - the campaign's uploader_counts reports them as inherited. Requires read:uploader.

Authorizations:
JWT
path Parameters
campaign_id
required
string
Example: abc123

The public ID of the campaign.

Responses

Response samples

Content type
application/vnd.api+json
{
  • "data": [
    ],
  • "meta": {
    }
}

Attributes

The attributes a brand collects. user_defined_id is the value an integration mapping's jebbit_var refers to.

List the attributes a brand collects

Returns the brand's attributes. user_defined_id is the value an integration mapping's jebbit_var refers to, so it is how you join a mapping back to the attribute it reads. attribute_pass says whether the attribute travels to integrations.

Pass filter[user_defined_id] to resolve specific attributes rather than listing the brand's whole set - a comma-separated list returns one record per match. That is the cheap way to answer "which attribute does this mapping read".

Authorizations:
JWT
query Parameters
filter[user_defined_id]
string
Example: filter[user_defined_id]=skin_concern,email

Return only the attributes with these user_defined_ids. Comma-separate for several. Unmatched values are ignored rather than erroring, so a response can be shorter than the list requested.

page[number]
integer >= 1
Example: page[number]=1

Which page to return, counting from 1. Omit both page parameters to receive the whole collection.

page[size]
integer [ 1 .. 1000 ]
Example: page[size]=100

How many records per page. Omit both page parameters to receive the whole collection.

Responses

Response samples

Content type
application/vnd.api+json
{
  • "data": [
    ],
  • "meta": {
    }
}

Get one attribute

Returns a single attribute by its public ID.

Authorizations:
JWT
path Parameters
trait_id
required
string
Example: trt123

The public ID of the attribute.

Responses

Response samples

Content type
application/vnd.api+json
{
  • "data": {
    }
}

Feeds

Manage product and data feeds used in campaign experiences.

List all feeds

Returns all data feeds for the authenticated business. Feeds are collections of structured data (e.g., product catalogs) used to power dynamic content in campaign experiences.

Authorizations:
JWT

Responses

Response samples

Content type
application/vnd.api+json
Example
{
  • "data": [
    ]
}

Create a feed

Creates a new data feed for the authenticated business. After creation, add columns and rows to populate the feed with data.

Authorizations:
JWT
Request Body schema: application/vnd.api+json
required

Feed details to create.

object

Responses

Request samples

Content type
application/vnd.api+json
{
  • "data": {
    }
}

Response samples

Content type
application/vnd.api+json
{
  • "data": {
    }
}

Get a feed

Returns a single feed by its public ID, including its name, source, and current status.

Authorizations:
JWT
path Parameters
feed_id
required
string
Example: abc123

The public ID of the feed to retrieve.

Responses

Response samples

Content type
application/vnd.api+json
{
  • "data": {
    }
}

Update a feed

Updates an existing feed's metadata. Only the provided attributes are modified; omitted attributes retain their current values.

Authorizations:
JWT
path Parameters
feed_id
required
string
Example: abc123

The public ID of the feed to update.

Request Body schema: application/vnd.api+json
required

Attributes to update on the feed. Only include fields you want to change.

object

Responses

Request samples

Content type
application/vnd.api+json
{
  • "data": {
    }
}

Response samples

Content type
application/vnd.api+json
{
  • "data": {
    }
}

Delete a feed

Permanently deletes a feed and all of its columns and rows. This action cannot be undone. Campaigns referencing this feed will lose access to its data.

Authorizations:
JWT
path Parameters
feed_id
required
string
Example: abc123

The public ID of the feed to delete.

Responses

Response samples

Content type
application/vnd.api+json
{
  • "errors": [
    ]
}

List columns for a feed

Returns all columns belonging to a specific feed. This is a convenience endpoint equivalent to filtering GET /api/v1/feed_columns by feed ID.

Authorizations:
JWT
path Parameters
feed_id
required
string
Example: abc123

The public ID of the feed whose columns to retrieve.

Responses

Response samples

Content type
application/vnd.api+json
Example
{
  • "data": [
    ]
}

List rows for a feed

Returns all rows belonging to a specific feed. This is a convenience endpoint equivalent to filtering GET /api/v1/feed_rows by feed ID.

Authorizations:
JWT
path Parameters
feed_id
required
string
Example: abc123

The public ID of the feed whose rows to retrieve.

Responses

Response samples

Content type
application/vnd.api+json
Example
{
  • "data": [
    ]
}

Feed Columns

Define and manage column schemas within data feeds.

List all feed columns

Returns feed columns filtered by one or more feed IDs. The filter[feed_id] query parameter is required and accepts an array of feed public IDs.

Authorizations:
JWT
query Parameters
filter[feed_id]
required
Array of strings
Example: filter[feed_id]=abc123&filter[feed_id]=def567

One or more feed public IDs to filter columns by. Only columns belonging to the specified feeds are returned.

Responses

Response samples

Content type
application/vnd.api+json
Example
{
  • "data": [
    ]
}

Create a feed column

Creates a new column within a feed. Columns define the schema of data that feed rows will contain (e.g., "Product Name", "Price", "Image URL").

Authorizations:
JWT
Request Body schema: application/vnd.api+json
required

Feed column details to create.

object

Responses

Request samples

Content type
application/vnd.api+json
{
  • "data": {
    }
}

Response samples

Content type
application/vnd.api+json
{
  • "data": {
    }
}

Get a feed column

Returns a single feed column by its public ID, including its name and the feed it belongs to.

Authorizations:
JWT
path Parameters
feed_column_id
required
string
Example: abc123

The public ID of the feed column to retrieve.

Responses

Response samples

Content type
application/vnd.api+json
{
  • "data": {
    }
}

Update a feed column

Updates an existing feed column. Currently supports renaming the column. Only the provided attributes are modified.

Authorizations:
JWT
path Parameters
feed_column_id
required
string
Example: abc123

The public ID of the feed column to update.

Request Body schema: application/vnd.api+json
required

Attributes to update on the feed column.

object

Responses

Request samples

Content type
application/vnd.api+json
{
  • "data": {
    }
}

Response samples

Content type
application/vnd.api+json
{
  • "data": {
    }
}

Delete a feed column

Permanently deletes a feed column. This removes the column definition from the feed schema. This action cannot be undone.

Authorizations:
JWT
path Parameters
feed_column_id
required
string
Example: abc123

The public ID of the feed column to delete.

Responses

Response samples

Content type
application/vnd.api+json
{
  • "errors": [
    ]
}

Feed Rows

Create and manage individual data rows within feeds.

List all feed rows

Returns feed rows filtered by one or more feed IDs. The filter[feed_id] query parameter is required and accepts an array of feed public IDs. Each row contains a data attribute with key-value pairs matching the feed's column schema.

Authorizations:
JWT
query Parameters
filter[feed_id]
required
Array of strings
Example: filter[feed_id]=abc123

One or more feed public IDs to filter rows by. Only rows belonging to the specified feeds are returned.

Responses

Response samples

Content type
application/vnd.api+json
Example
{
  • "data": [
    ]
}

Create a feed row

Creates a new data row within a feed. The data attribute should contain key-value pairs matching the feed's column schema. Each row must have a unique product_identifier within its feed.

Authorizations:
JWT
Request Body schema: application/vnd.api+json
required

Feed row data to create.

object

Responses

Request samples

Content type
application/vnd.api+json
{
  • "data": {
    }
}

Response samples

Content type
application/vnd.api+json
{
  • "data": {
    }
}

Get a feed row

Returns a single feed row by its public ID, including its product identifier and column data.

Authorizations:
JWT
path Parameters
feed_row_id
required
string
Example: abc123

The public ID of the feed row to retrieve.

Responses

Response samples

Content type
application/vnd.api+json
{
  • "data": {
    }
}

Update a feed row

Updates an existing feed row's data. Only the provided attributes are modified; omitted attributes retain their current values.

Authorizations:
JWT
path Parameters
feed_row_id
required
string
Example: abc123

The public ID of the feed row to update.

Request Body schema: application/vnd.api+json
required

Attributes to update on the feed row.

object

Responses

Request samples

Content type
application/vnd.api+json
{
  • "data": {
    }
}

Response samples

Content type
application/vnd.api+json
{
  • "data": {
    }
}

Delete a feed row

Permanently deletes a feed row. This action cannot be undone.

Authorizations:
JWT
path Parameters
feed_row_id
required
string
Example: abc123

The public ID of the feed row to delete.

Responses

Response samples

Content type
application/vnd.api+json
{
  • "errors": [
    ]
}

Error Codes

All error responses follow the JSON:API error format. Each response body contains an errors array with one or more error objects.

Status Title When
400 Bad Request Missing or malformed request parameters
401 Unauthorized Missing or expired bearer token
403 Forbidden Insufficient permissions for this action
404 Not Found Resource does not exist or belongs to another business
422 Unprocessable Entity Semantic validation failure (e.g., reserved value)
500 Internal Server Error Unexpected server-side failure

Example error response:

{
  "errors": [
    {
      "status": 400,
      "title": "Bad Request",
      "detail": "The 'name' field is required."
    }
  ]
}

Handling errors in your integration:

  • Always check the HTTP status code before parsing the response body.
  • The detail field provides a human-readable explanation specific to the error.
  • For 401 errors, request a new token via POST /api/v1/auth.
  • For 500 errors, retry the request with exponential backoff.