API Reference

Public REST endpoints reachable with a personal access token.

Authentication

Issue a personal access token from Profile → Integrations → Access tokens with the scope an endpoint requires below, then send it as "Authorization: Bearer velocis_pat_...". A token only reaches what its scopes allow — it never bypasses your own project permissions.

Issues

GET/issues

List issues

Returns a page of issues the token owner can see, newest first. Every filter is optional; limit is clamped to 1000 server-side.

Required scope: issues:read

Parameters

Name	In	Required	Type	Description
`allocatable`	query	Optional	`string`	`true` or `1` to drop issues whose status cannot receive a resource allocation. Adds to any `excludeStatuses` you pass rather than replacing it.
`assignedToMe`	query	Optional	`string`	`true` or `1` to narrow to issues assigned to the caller. Applied outside `q`, so an `OR` in `q` cannot widen past it.
`assigneeId`	query	Optional	`string`	Narrow to one assignee, by user id — or the literal `unassigned` for issues with nobody assigned.
`excludeStatuses`	query	Optional	`string`	Comma-separated statuses to exclude. Parsed exactly like `statuses`.
`facets`	query	Optional	`string`	Comma-separated dimensions to count over the same filters, returned as `meta.facets`: `status`, `priority`, `assignee`, `project`, `sprint`, `type`, `epic`, `milestone`. Each dimension is counted without its own filter.
`filteredFacets`	query	Optional	`string`	Like `facets`, but each dimension is counted under the FULL query, its own filter included — how many of the matching issues carry each value. Returned as `meta.filteredFacets`. In both, a bucket is `{ groupId, groupValue, totalCount }`; an `epic` bucket other than `no-epic` also carries `epicStatus`, the status of the epic issue itself; a `milestone` bucket other than `none` also carries the milestone `status` (`open` / `closed`) and its `position` in the project order. A `filteredFacets` bucket also carries `storyPoints`, the points of the bucket under the estimate rule in force: the own points of its members; with `advanced.features.leafEstimateRollup` on, the points of the members that are estimate leaves among ALL the matching issues (a sub-issue outside the result hides nothing), so the buckets add up to the result and the buckets of a sprint to its summary. A `milestone` bucket is always the closure minus the descendants assigned to another milestone. It is seeded from the matching members, so it equals the milestone progress points only when the list is unfiltered.
`groupBy`	query	Optional	`string`	Field being grouped by, such as `status` or `assignee`. Takes effect only together with `groupValue`.
`groupValue`	query	Optional	`string`	Which group within `groupBy` to return — one status, one assignee id (`unassigned` for none), one epic id (`no-epic`), or one milestone id (`none`).
`includeArchived`	query	Optional	`string`	`true` or `1` to return archived issues alongside active ones.
`limit`	query	Optional	`number`	Page size. Defaults to 50 and is clamped to 1000.
`onlyArchived`	query	Optional	`string`	`true` or `1` to return only archived issues. Checked before `includeArchived`, so the two cannot contradict each other.
`page`	query	Optional	`number`	1-based page number. Defaults to 1.
`projectId`	query	Optional	`string`	Narrow to one project, by id. Use `projectIds` for several.
`projectIds`	query	Optional	`string`	Comma-separated project ids, to query across several projects at once. Entries that are not ids are dropped.
`q`	query	Optional	`string`	Search query in the advanced-search grammar (`status:todo assignee:me is:open sort:priority-desc login`), combined with every other filter; at most 2000 characters. Free text ranks by relevance unless `sortBy` or a `sort:` token is set. Tokens that did not apply are listed in `meta.query.ignoredTokens`; the ordering that ran is `meta.appliedSort`.
`sortBy`	query	Optional	`string`	Field to sort by. A field outside the allowed set leaves the default ordering in place. Wins over a `sort:` token in `q`.
`sortOrder`	query	Optional	`string`	`asc` or `desc`. Applies only with `sortBy`; any other value reads as `asc`.
`sprintId`	query	Optional	`string`	Narrow to the issues in one sprint, by id. Applied outside `q`, so an `OR` in `q` cannot widen past it.
`status`	query	Optional	`string`	Narrow to a single status. Use `statuses` to pass several.
`statuses`	query	Optional	`string`	Comma-separated statuses to include. Unrecognised values are dropped; if none survive, the filter is not applied rather than matching nothing.
`tagIds`	query	Optional	`string`	Comma-separated tag ids. Entries that are not ids are dropped.
`unallocated`	query	Optional	`string`	`true` or `1` to return only issues that have no resource allocations.

Responses

200

A page of issues. Each row carries `allocation: { capability: 'manage' | 'self' | 'none', reason?: 'no_permission' | 'issue_archived' | 'issue_container' | 'issue_cancelled' }` — what the caller's CURRENT credential may do. Allocation routes do not accept personal access tokens, so a token request always reads `none` / `no_permission`. `meta.stats` counts the matching issues per status; `meta.query` is the parsed `q` (its `ignoredTokens` did not apply); `meta.appliedSort` is the ordering that ran; `meta.facets` is present when `facets` was requested.

403

The token lacks `issues:read`.

POST/issues

Create an issue

Creates an issue in the given project. The token owner must have permission to create issues there — the issues:write scope narrows the token, it does not grant access.

Required scope: issues:write

Request body

{
  "properties": {
    "assigneeId": {
      "description": "Assignee. Must be a member of the project.",
      "format": "uuid",
      "type": "string"
    },
    "attachmentLinks": {
      "description": "External file links (typically Google Drive). Appended to the description as a markdown list.",
      "items": {
        "properties": {
          "driveFileId": {
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "url": {
            "type": "string"
          }
        },
        "type": "object"
      },
      "type": "array"
    },
    "attachments": {
      "description": "Attachments already uploaded, referenced by storage key.",
      "items": {
        "properties": {
          "id": {
            "description": "Provider-side id (a Drive file id, for `drive`).",
            "type": "string"
          },
          "mimeType": {
            "description": "MIME type, when known.",
            "type": "string"
          },
          "name": {
            "description": "Display name.",
            "type": "string"
          },
          "size": {
            "description": "Size in bytes.",
            "type": "number"
          },
          "type": {
            "description": "Where the file lives.",
            "enum": [
              "drive",
              "url",
              "file"
            ],
            "type": "string"
          },
          "url": {
            "description": "Resolvable URL to the file.",
            "type": "string"
          }
        },
        "required": [
          "type",
          "name",
          "url"
        ],
        "type": "object"
      },
      "type": "array"
    },
    "attachmentsInline": {
      "description": "Base64 attachments from the Gmail add-on. Prefer multipart upload — this path exists for Apps Script, which cannot send multipart.",
      "items": {
        "properties": {
          "contentBase64": {
            "type": "string"
          },
          "filename": {
            "type": "string"
          },
          "mimeType": {
            "type": "string"
          }
        },
        "type": "object"
      },
      "type": "array"
    },
    "attachmentsPending": {
      "description": "Defer the creation notification because attachments follow in a second request (the MCP create→attach flow). REST clients omit this.",
      "type": "boolean"
    },
    "attributes": {
      "additionalProperties": true,
      "description": "Values for the project’s custom fields, keyed by field id. Unknown keys are ignored.",
      "type": "object"
    },
    "description": {
      "description": "Markdown body of the issue.",
      "type": "string"
    },
    "dueDate": {
      "description": "Due date (ISO 8601).",
      "format": "date",
      "type": "string"
    },
    "endDate": {
      "description": "Planned end date (ISO 8601).",
      "format": "date",
      "type": "string"
    },
    "milestoneId": {
      "description": "Milestone (wave) of the same project. Must be open; with a context container the issue must be its descendant. On an update, `null` clears it.",
      "format": "uuid",
      "nullable": true,
      "type": "object"
    },
    "parentIssueId": {
      "description": "Parent issue. On an update, `null` detaches the issue and promotes it to a root.",
      "format": "uuid",
      "nullable": true,
      "type": "object"
    },
    "priority": {
      "description": "Priority.",
      "enum": [
        "low",
        "medium",
        "high",
        "urgent"
      ],
      "type": "string"
    },
    "projectId": {
      "description": "The project this issue belongs to.",
      "format": "uuid",
      "type": "string"
    },
    "qaPolicy": {
      "description": "Whether this issue needs QA. `null` leaves it undecided, which falls back to the project default.",
      "enum": [
        "required",
        "skip"
      ],
      "nullable": true,
      "type": "string"
    },
    "severity": {
      "description": "Post-release severity, for BUG issues.",
      "enum": [
        "low",
        "medium",
        "high"
      ],
      "type": "string"
    },
    "startDate": {
      "description": "Planned start date (ISO 8601).",
      "format": "date",
      "type": "string"
    },
    "status": {
      "description": "Initial status. Omit to use the project workflow’s starting status — not every value is reachable from every other, so a transition the workflow forbids is rejected.",
      "enum": [
        "backlog",
        "todo",
        "in_progress",
        "in_review",
        "done",
        "cancelled"
      ],
      "type": "string"
    },
    "storyPoints": {
      "description": "Story points. One of 0.5, 1, 2, 3, 5, 8, 13, 21, 34, 55, 89 — plus 0.25 for BUG and TEST issues. Epics reject this field.",
      "type": "number"
    },
    "tagIds": {
      "description": "Tags to attach, by id. Tags are per-project.",
      "items": {
        "format": "uuid",
        "type": "string"
      },
      "type": "array"
    },
    "title": {
      "description": "The issue title.",
      "example": "Login page 500s",
      "type": "string"
    },
    "type": {
      "description": "Issue type. Some fields are type-dependent — an epic rejects story points, for instance.",
      "enum": [
        "bug",
        "feature",
        "task",
        "story",
        "epic",
        "improvement",
        "documentation",
        "question",
        "test",
        "initiative"
      ],
      "type": "string"
    }
  },
  "required": [
    "title",
    "projectId"
  ],
  "type": "object"
}

Responses

201

The created issue.

403

The token lacks `issues:write`, or its owner may not create issues in this project.

GET/issues/{id}

Get one issue

Returns a single issue by its id. 403 when the token owner cannot see it — the scope is a ceiling over their own permissions, never a grant.

Required scope: issues:read

Parameters

Name	In	Required	Type	Description
`id`	path	Required	`string`	The issue's id. Not the issue number — `VEL-101` is rejected here.

Responses

200

The issue.

404

No such issue.

Projects

GET/projects

List projects

Returns the projects the token owner is a member of. Pass minimal=true for id + name only, which is what a script addressing issues usually needs.

Required scope: projects:read

Parameters

Name	In	Required	Type	Description
`includeArchived`	query	Optional	`string`	`true` or `1` to return archived projects alongside active ones.
`minimal`	query	Optional	`string`	`true` or `1` to return only id and name per project — enough to address issues, and much smaller.

Responses

200

The projects.

403

The token lacks `projects:read`.

GET/projects/{id}

Get one project

Returns a single project by its id, including its workflow metadata. 403 when the token owner is not a member.

Required scope: projects:read

Parameters

Name	In	Required	Type	Description
`id`	path	Required	`string`	The project's id, as returned by `GET /projects`.

Responses

200

The project.

404

No such project.