API 레퍼런스

개인 액세스 토큰으로 호출할 수 있는 공개 REST 엔드포인트입니다.

인증

프로필 → 통합 설정 → 액세스 토큰에서 아래 엔드포인트가 요구하는 스코프로 개인 액세스 토큰을 발급한 뒤, "Authorization: Bearer velocis_pat_..."로 전송하세요. 토큰은 그 스코프가 허용하는 만큼만 접근하며, 본인의 프로젝트 권한을 우회하지 않습니다.

로그인하고 토큰 발급하기

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.

필요 스코프: issues:read

파라미터

이름	위치	필수 여부	타입	설명
`allocatable`	query	선택	`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	선택	`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	선택	`string`	Narrow to one assignee, by user id — or the literal `unassigned` for issues with nobody assigned.
`excludeStatuses`	query	선택	`string`	Comma-separated statuses to exclude. Parsed exactly like `statuses`.
`facets`	query	선택	`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	선택	`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	선택	`string`	Field being grouped by, such as `status` or `assignee`. Takes effect only together with `groupValue`.
`groupValue`	query	선택	`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	선택	`string`	`true` or `1` to return archived issues alongside active ones.
`limit`	query	선택	`number`	Page size. Defaults to 50 and is clamped to 1000.
`onlyArchived`	query	선택	`string`	`true` or `1` to return only archived issues. Checked before `includeArchived`, so the two cannot contradict each other.
`page`	query	선택	`number`	1-based page number. Defaults to 1.
`projectId`	query	선택	`string`	Narrow to one project, by id. Use `projectIds` for several.
`projectIds`	query	선택	`string`	Comma-separated project ids, to query across several projects at once. Entries that are not ids are dropped.
`q`	query	선택	`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	선택	`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	선택	`string`	`asc` or `desc`. Applies only with `sortBy`; any other value reads as `asc`.
`sprintId`	query	선택	`string`	Narrow to the issues in one sprint, by id. Applied outside `q`, so an `OR` in `q` cannot widen past it.
`status`	query	선택	`string`	Narrow to a single status. Use `statuses` to pass several.
`statuses`	query	선택	`string`	Comma-separated statuses to include. Unrecognised values are dropped; if none survive, the filter is not applied rather than matching nothing.
`tagIds`	query	선택	`string`	Comma-separated tag ids. Entries that are not ids are dropped.
`unallocated`	query	선택	`string`	`true` or `1` to return only issues that have no resource allocations.

응답

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.

필요 스코프: issues:write

요청 본문

{
  "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"
}

응답

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.

필요 스코프: issues:read

파라미터

이름	위치	필수 여부	타입	설명
`id`	path	필수	`string`	The issue's id. Not the issue number — `VEL-101` is rejected here.

응답

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.

필요 스코프: projects:read

파라미터

이름	위치	필수 여부	타입	설명
`includeArchived`	query	선택	`string`	`true` or `1` to return archived projects alongside active ones.
`minimal`	query	선택	`string`	`true` or `1` to return only id and name per project — enough to address issues, and much smaller.

응답

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.

필요 스코프: projects:read

파라미터

이름	위치	필수 여부	타입	설명
`id`	path	필수	`string`	The project's id, as returned by `GET /projects`.

응답

200

The project.

404

No such project.