Skip to content
Documentation

Data & backend

Using the Vorx API

Call Vorx from your own scripts and integrations with a personal API key and GraphQL.

Use the Vorx GraphQL API when you want to read or update workspace data from outside the app — backups, internal tools, or automations you run yourself.

This is different from APIs and automations inside a generated app (calling Stripe, Slack, and so on). Here you are calling Vorx as the client.

Create an API key

  1. Open Settings → Personal → API keys.
  2. Click Create API key and give it a label.
  3. Copy the key when it is shown. Vorx only displays the full secret once.

Keys look like vorx_api_ followed by a long random string. Copy the whole value, including vorx_api_. A key sent without its prefix is refused as an unknown token.

Authenticate

Send the key as a Bearer token on every request:

Authorization: Bearer vorx_api_your_key_here

No session cookie or company header is required — the key is already scoped to your user and workspace.

Endpoint

Prompt
POST https://www.vorx.com/graphql
Content-Type: application/json

Example request

curl https://www.vorx.com/graphql \
  -H "Authorization: Bearer vorx_api_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"query":"{ currentEmail companies { nodes { id name code } } }"}'

A successful response includes your email and the companies the key can access. From there you can query projects, members, and other workspace data the same way the Vorx app does.

Errors

A request that fails authentication is refused before any query runs. The response has HTTP status 401 and a JSON body with an error message:

  • No Authorization header: Access denied - Valid API key or session required
  • A header that is not in the form Bearer <key>: Invalid Authorization header format. Expected: 'Bearer <token>'
  • A Bearer token that is not a Vorx API key: Access denied - a Bearer token must be a Vorx API key (vorx_api_…)
  • A vorx_api_ key that is unknown or revoked, or whose user or workspace is no longer active: Access denied - Invalid API key

If Vorx cannot check the key at that moment, the response is HTTP status 503 with a Retry-After header (in seconds) and the error message Could not check this API key right now. It may be fine; retry shortly. The key has not been rejected. Wait for the Retry-After time and send the request again; do not replace the key.

A query that is not valid for the schema, such as one asking for a field that does not exist, returns HTTP status 400 and an errors array instead. Each entry has a message saying what was wrong.

A query that runs for more than 30 seconds in the database is stopped and returns an error.

Rate limits

Each API key can make up to 1,500 requests per hour. A request over the limit is refused with HTTP status 429 and this error message:

Too many requests from this API key or access token, please try again later

Wait for the hour to pass, then send the request again.

Building and publishing with a key

The GraphQL API reads and updates workspace data. To build, change and publish projects from your own code, a key can also call four builder routes on https://www.vorx.com. These are the routes the MCP connection uses, and the key needs the same permission: tick Let AI assistants use this key (Claude, ChatGPT) when you create it. A key without it is refused with HTTP status 401 and "error": "api_key_not_enabled_for_ai".

  • Create a project: POST /builder/project/scaffold with projectId (a new UUID you choose), kickoffPrompt (your brief), optional appType and project.name
  • Change a project: POST /builder/chat/message with projectId, message (the change, in plain English)
  • Check a build: GET /builder/chat/progress?projectId=…, no body
  • Publish a project: POST /builder/project/{projectId}/publish with optional slug

What to know before you script against them:

  • Create only creates. projectId must be a UUID, or the request is refused with 400 invalid_project_id. Sending scaffold with the id of a project that already exists is refused with 409 project_exists; change an existing project with chat/message.
  • The key's own workspace and person are used. Any other fields you send are ignored.
  • The responses are the ones the Vorx app reads, so their shape can change. If you want a stable interface, use the MCP connection.
  • Daily limits apply to scaffold, chat/message and publish: 50 builds started (every create or change request counts), 100 credits charged and 20 publishes per key per UTC day. A build over its limit is refused with 429 api_key_cap, and a publish with 429 api_key_publish_cap. If Vorx cannot count the day's usage, the request is refused rather than allowed: 429 with "code": "unmeasured", or 503 if the start could not be recorded. Wait a minute and try again. chat/progress has no daily limit.
  • Builds take several minutes. Poll chat/progress every 20–30 seconds rather than continuously.

Webhooks

Vorx does not send webhooks yet. The Zapier integration polls Vorx for new data instead.

Keep keys safe

  • Treat the key like a password — do not commit it or put it in client-side code.
  • Prefer environment variables or a secret store in your scripts.
  • Revoke a key anytime from Settings → Personal → API keys if it leaks or you no longer need it.

Revoking a key takes effect on the next request. If a member is removed from the workspace, their keys stop working within two minutes.