Read-only API

Access and availability

This guide describes the read-only API preview. Check API keys in your Studio account for availability. Access requires an active, paid Studio or Scale subscription; credit packs alone do not qualify.

API reads do not consume generation credits, even when your balance is zero. This version cannot upload photos, start generation, download files, modify projects or manage billing. It is an HTTP API, not an MCP server or ChatGPT plugin.

Create a key and connect

1. Open API keys in your Studio account, name the key for your integration and create it. Each key has the metadata:read scope.
2. Copy the secret when it appears: it is shown only once. Store it in a server-side secret manager or an environment variable named SEGMENTIT_API_KEY.
3. Send the key in the Authorization: Bearer header over HTTPS. The example below reads an existing environment variable; do not replace it with a secret in shared code.

cURL · Bash

curl --fail-with-body --get \
  'https://segmentit.com/api/v1/projects' \
  --data-urlencode 'limit=20' \
  --header \
  "Authorization: Bearer $SEGMENTIT_API_KEY"

Node.js · Server-side JavaScript

Set SEGMENTIT_API_KEY on your server, then run this example with Node.js 22 or later. Create your key in Studio → Account → API.

const apiKey = process.env.SEGMENTIT_API_KEY;
if (!apiKey) throw new Error('Set SEGMENTIT_API_KEY');

const response = await fetch(
  'https://segmentit.com/api/v1/projects?limit=20',
  {
    headers: { Authorization: `Bearer ${apiKey}` },
    redirect: 'error',
    signal: AbortSignal.timeout(10_000),
  },
);

if (!response.ok) {
  const retryAfter = response.headers.get('Retry-After');
  throw new Error(
    `API error: ${response.status}` +
    (retryAfter ? `; retry after ${retryAfter}s` : ''),
  );
}

const { data: projects, pagination } = await response.json();
console.log(projects);
console.log('Next offset:', pagination.nextOffset);

Available endpoints

The base URL is https://segmentit.com/api/v1. Every request is authenticated and limited to the key owner’s data. Identifiers are UUIDs returned by the API. JSON fields and status values stay in English in every language.

Job responses report the last saved state: queued, running, succeeded, failed or cancelled. Reading a job does not refresh the processing provider or trigger work. Refresh the project in the Studio when you need its latest processing state.

OpenAPI schema · JSON

Pagination and responses

Collections return data and pagination. The default limit is 20; choose 1–50 items and an offset from 0 to 10000. Use nextOffset for the next request and stop when it is null. A single project or job returns only a data object. Dates use ISO 8601.

{
  "data": [
    {
      "id": "7b5e26c3-e260-409a-bbb9-b5719f9dbfb0",
      "name": "Launch",
      "kind": "personal",
      "latestJobId": null,
      "createdAt": "2026-10-09T10:00:00.000Z",
      "updatedAt": "2026-10-09T10:00:00.000Z"
    }
  ],
  "pagination": {
    "limit": 20,
    "offset": 0,
    "nextOffset": null
  }
}

Limits, errors and retries

An account can have 3 active keys. Keys expire after 90 days. All keys share a limit of 60 requests per minute per account. For a 429 response, wait the number of seconds in Retry-After before retrying; avoid continuous polling.

Eligibility is checked on every request. When your subscription is no longer eligible, API requests return 403 even if the key has not expired. You can still revoke your keys in the Studio. A revoked or expired key returns 401; create a replacement when access is available.

{
  "error": {
    "code": "invalid_api_key",
    "message": "A valid API key is required."
  }
}

Keep your integration private

Run requests on your server or in a trusted local script. Never put keys in a URL, browser JavaScript, a public repository, screenshots or logs. Revoke a leaked key immediately. A key can read metadata across your own projects, not just one selected project.

Responses contain metadata only: no source photos, masks, GLB content, file URLs or provider credentials. Keep using the Studio to view and download your creations.