GraphQL API
Query and mutate Velocity data with the GraphQL API.
Availability and access
The GraphQL API and external-service OAuth API are available on every plan. Individual operations still require the appropriate credential, workspace membership, role and feature entitlement. MCP access has a separate Pro-or-higher requirement.
For your own scripts, use a workspace or personal API key. For customer-authorized integrations, use external-service OAuth: its supported REST endpoints are /api/v1/identity, /api/v1/issues and /api/v1/issues/:id. For no-code triggers and actions, see the separate automation API.
Endpoint
POST https://velocity.quest/api/graphqlUse HTTP POST for queries and mutations. HTTP GET supports queries only. For POST, send a JSON body with a query field and optionalvariables. For GET, URL-encode these as query parameters and send Content-Type: application/json for the CSRF check.
Let customers authorize your service with OAuth for External Services. Register an app, request scoped access to selected workspaces, and use the supported GraphQL operations or REST identity and issue endpoints. The guide includes a runnable Node.js example and an endpoint/permission matrix.
Quick Example
Replace the key, workspace slug and workspace UUID with your own values. Find the UUID with { workspace(slug: "your-workspace") { id } }. The workspace header selects context; it does not replace required query arguments.
curl -X POST https://velocity.quest/api/graphql \
-H "Authorization: Bearer vel_your_api_key" \
-H "X-Workspace-Slug: your-workspace" \
-H "Content-Type: application/json" \
-d '{
"query": "query Issues($workspaceId: ID!) { issues(workspaceId: $workspaceId, pagination: { first: 20 }) { edges { node { id identifier title status { name } } } pageInfo { hasNextPage endCursor } } }",
"variables": { "workspaceId": "YOUR_WORKSPACE_UUID" }
}'Schema Overview
Available operations depend on your credential, scopes, workspace role and product limits. The tables below describe the general schema; external OAuth applications use the smaller delegated API capability set. Credential management, account security and other unlisted operations are unavailable to external app tokens.
Queries
| Query | Description |
|---|---|
workspace(slug) | Get workspace by slug |
workspaces | List workspaces accessible to the current credential |
issues(workspaceId, filter, sort, pagination) | List/filter issues |
issue(id) | Get a single issue |
projects(workspaceId) | List projects |
project(id) | Get a single project |
cycles(teamId) | List cycles |
documents(workspaceId) | List documents |
teams(workspaceId) | List teams |
labels(workspaceId) | List labels |
prds(workspaceId, filter, first, offset) | List PRDs; use prd(id) for requirements and coverage |
userStories(workspaceId, filter, first, offset) | List user stories; use userStory(id) for details |
notifications | Get user notifications |
apiKeys(workspaceId) | List workspace API keys |
userApiKeys | List personal API keys for the current user |
Mutations
| Mutation | Description |
|---|---|
createIssue | Create a new issue |
updateIssue | Update an issue |
deleteIssue | Delete an issue |
createComment | Add a comment |
createProject | Create a project |
updateProject | Update a project |
createCycle | Create a cycle |
createDocument | Create a document |
createPrd / updatePrd | Create and edit PRDs |
createPrdRequirement / updatePrdRequirement | Manage PRD requirements |
createUserStory / updateUserStory / splitUserStory | Create, edit and split stories |
createIssuesFromStories / linkIssueToStory | Create or link engineering issues for stories |
createWorkspace | Create a new workspace |
updateWorkspace | Update workspace name, slug, or settings |
deleteWorkspace | Delete a workspace (owner only) |
createUserApiKey | Create a personal API key |
revokeUserApiKey | Revoke a personal API key |
Pagination
issues and collection queries ending in Page(such as projectsPage, teamsPage and documentsPage) use Relay-style cursor pagination. The response includes:
{
"edges": [
{
"cursor": "base64_encoded_cursor",
"node": { "id": "...", ... }
}
],
"pageInfo": {
"hasNextPage": true,
"endCursor": "base64_encoded_cursor"
},
"totalCount": 42
}Pass endCursor as pagination.after, with pagination.first, while hasNextPage is true. Legacy list fields such as projects, cycles and documents return arrays. prds and userStories return nodes/totalCountand use first/offset. Check the field's schema before choosing a pagination strategy.
Error Handling
GraphQL errors are returned in the errors array with a message and optional extensions containing the error code:
{
"errors": [{
"message": "Issue not found",
"extensions": {
"code": "NOT_FOUND"
}
}]
}Next Steps
- Authentication — API keys, OAuth, session tokens
- OAuth for External Services — registration, user consent, scoped GraphQL/REST access and token lifecycle
- Private Attachments — screenshots, binary uploads, MCP/CLI workflows and safe retries
- Rate Limits — limits by auth type