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/graphql

Use 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.

Build a Connect Velocity integration

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

QueryDescription
workspace(slug)Get workspace by slug
workspacesList 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
notificationsGet user notifications
apiKeys(workspaceId)List workspace API keys
userApiKeysList personal API keys for the current user

Mutations

MutationDescription
createIssueCreate a new issue
updateIssueUpdate an issue
deleteIssueDelete an issue
createCommentAdd a comment
createProjectCreate a project
updateProjectUpdate a project
createCycleCreate a cycle
createDocumentCreate a document
createPrd / updatePrdCreate and edit PRDs
createPrdRequirement / updatePrdRequirementManage PRD requirements
createUserStory / updateUserStory / splitUserStoryCreate, edit and split stories
createIssuesFromStories / linkIssueToStoryCreate or link engineering issues for stories
createWorkspaceCreate a new workspace
updateWorkspaceUpdate workspace name, slug, or settings
deleteWorkspaceDelete a workspace (owner only)
createUserApiKeyCreate a personal API key
revokeUserApiKeyRevoke 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