GraphQL API

Query and mutate Velocity data with the GraphQL API.

Endpoint

POST https://app.velocity.dev/api/graphql

All API requests are sent as HTTP POST requests to the GraphQL endpoint. The request body must be JSON with a query field and optionalvariables.

Quick Example

curl -X POST https://app.velocity.dev/api/graphql \
  -H "Authorization: Bearer vel_your_api_key" \
  -H "X-Workspace-Slug: your-workspace" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "{ issues(teamId: \"team_123\") { edges { node { id identifier title status { name } } } } }"
  }'

Schema Overview

The API provides queries and mutations for all Velocity resources:

Queries

Query	Description
`workspace(slug)`	Get workspace by slug
`issues(teamId, 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
`notifications`	Get user notifications

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

Pagination

List queries 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 the endCursor as the after parameter to fetch the next page.

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
Rate Limits — limits by auth type