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
- Open Settings → Personal → API keys.
- Click Create API key and give it a label.
- 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
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
Authorizationheader: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/scaffoldwithprojectId(a new UUID you choose),kickoffPrompt(your brief), optionalappTypeandproject.name - Change a project:
POST /builder/chat/messagewithprojectId,message(the change, in plain English) - Check a build:
GET /builder/chat/progress?projectId=…, no body - Publish a project:
POST /builder/project/{projectId}/publishwith optionalslug
What to know before you script against them:
- Create only creates.
projectIdmust be a UUID, or the request is refused with 400invalid_project_id. Sendingscaffoldwith the id of a project that already exists is refused with 409project_exists; change an existing project withchat/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/messageandpublish: 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 429api_key_cap, and a publish with 429api_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/progresshas no daily limit. - Builds take several minutes. Poll
chat/progressevery 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.
Related
- Secrets — credentials your generated apps use to call other services.
- APIs and automations — calling external APIs from inside a Vorx app.
- Connect Claude and other AI assistants — let an assistant build and publish for you.