API Ryoma: projects
Projects and their repos
This page is generated from
openapi.yamlbynpm run gen, so do not edit it by hand. Authentication is described on the overview page.
/v1/projectsAdminProjects and repos I can view
Every role of the organization (owner, admin, member, viewer) sees every project of the organization. Tara is the source of truth: Ryoma mirrors GET /v1/orgs/{org}/projects of Tara (key, name, repos) using the caller's own credential, cached for about 60 seconds per organization, and a project deleted in Tara disappears from this list (its notification emails and quotas are kept in case it is created again). If Tara cannot be reached, the last known list is returned.
Responses
| Code | Description | Type |
|---|---|---|
| 200 | List of projects | application/json · object |
| 401 | Missing or invalid token | application/problem+json · object |
| 503 | Tara did not answer the check of which projects the caller can see (private projects). Ryoma never treats this as "sees everything"; retry after the Retry-After header (30 seconds) | application/problem+json · object |
Example response
{
"items": [
{
"key": "string",
"scm": {},
"name": "string",
"org": "string",
"repos": [],
"contacts": []
}
]
}Call with curl
curl "https://ryoma.phillipcli.cloud/v1/projects" \
-H "Authorization: Bearer $TARA_TOKEN"/v1/projects/{key}AdminSet the Ryoma-only settings of a project (org owner and admin)
Projects are managed in Tara: creating a project, renaming it, or changing its repos is not allowed here and answers 403 ("Projects are managed in Tara"). Only the settings Ryoma owns (contacts) can be written, for a project that exists. name and repos are optional; when sent they must equal the current values (so older clients that send the whole project keep working).
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
key | path | string | yes |
Body (application/json)
| Field | Type | Required | Description |
|---|---|---|---|
name | string | Optional; must equal the current name (it comes from Tara) | |
repos | string[] | Optional; must equal the project's current repos (they come from Tara) | |
contacts | string[] | Email addresses that receive the project's risk alerts and weekly digest (PM); empty means they only go to the shared channel |
Responses
| Code | Description | Type |
|---|---|---|
| 200 | Project saved | application/json · object |
| 400 | Invalid parameters | application/problem+json · object |
| 401 | Missing or invalid token | application/problem+json · object |
| 403 | Forbidden | application/problem+json · object |
| 404 | Not found. Also returned for a project that exists but is private and the caller cannot see (never 403, so a private project cannot be discovered) | application/problem+json · object |
| 503 | Tara did not answer the check of which projects the caller can see (private projects). Ryoma never treats this as "sees everything"; retry after the Retry-After header (30 seconds) | application/problem+json · object |
Example response
{
"key": "string",
"scm": {
"connected": false,
"via": "scm_connection",
"reason": "scm_connection_required",
"message": "string",
"repos": [
{}
]
},
"name": "string",
"org": "string",
"repos": [
"string"
],
"contacts": [
"string"
]
}Call with curl
curl -X PUT "https://ryoma.phillipcli.cloud/v1/projects/<key>" \
-H "Authorization: Bearer $TARA_TOKEN" \
-H "Content-Type: application/json" \
-d '{"name":"string","repos":["string"],"contacts":["string"]}'/v1/projects/{key}AdminNot allowed - delete the project in Tara
Always answers 403 ("Projects are managed in Tara"). Ryoma drops a project from its list when Tara no longer has it.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
key | path | string | yes |
Responses
| Code | Description | Type |
|---|---|---|
| 401 | Missing or invalid token | application/problem+json · object |
| 403 | Forbidden | application/problem+json · object |
| 404 | Not found. Also returned for a project that exists but is private and the caller cannot see (never 403, so a private project cannot be discovered) | application/problem+json · object |
| 503 | Tara did not answer the check of which projects the caller can see (private projects). Ryoma never treats this as "sees everything"; retry after the Retry-After header (30 seconds) | application/problem+json · object |
Call with curl
curl -X DELETE "https://ryoma.phillipcli.cloud/v1/projects/<key>" \
-H "Authorization: Bearer $TARA_TOKEN"/v1/projects/{key}/qualityAdminData quality warnings of a project, each with how to fix it (every role of the organization)
Warnings that tell why Flow numbers may be wrong: closed tasks without type: (coverage below 70% of the tasks closed in the last 8 weeks), closed tasks without level:, repos outside the organization's GitHub App installation or GitLab group, repos missing the standard labels (status: …, type: …, level: …), and machines that started a Claude Code session in the last 7 days but sent no telemetry. For a project whose tasks come from a tracker (Jira) the repo and label warnings do not apply, type_coverage_low and closed_without_level read the issue type and size field instead of labels, and tracker_unreachable appears (with the reason, no secrets) while the last read of the tracker failed. Task data is read at every sync, so a warning disappears at the next sync after the cause is fixed (label warnings: at most about a minute after). Names of people (items of telemetry_silent) are shown to the organization owner and admins only; other roles get the count. fix.kind tells the client what to offer (label_tasks, create_labels, connect_repo, setup_telemetry, check_tracker); fix.command is the equivalent Phillip command. ph ryoma report --project prints the same warnings. Not a new metric: it only says when a metric lacks data.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
key | path | string | yes |
Responses
| Code | Description | Type |
|---|---|---|
| 200 | Warnings (empty list when the data is in good shape) | application/json · object |
| 401 | Missing or invalid token | application/problem+json · object |
| 403 | Forbidden | application/problem+json · object |
| 404 | Not found. Also returned for a project that exists but is private and the caller cannot see (never 403, so a private project cannot be discovered) | application/problem+json · object |
| 503 | Tara did not answer the check of which projects the caller can see (private projects). Ryoma never treats this as "sees everything"; retry after the Retry-After header (30 seconds) | application/problem+json · object |
Example response
{
"project": "string",
"checkedAt": "2026-11-01T00:00:00Z",
"warnings": [
{
"code": "type_coverage_low",
"message": "string",
"count": 0,
"total": 0,
"fix": {}
}
]
}Call with curl
curl "https://ryoma.phillipcli.cloud/v1/projects/<key>/quality" \
-H "Authorization: Bearer $TARA_TOKEN"/v1/projects/{key}/releasesAdminReleases of a project with release wait time and AI cost per release (every role of the organization)
Releases of the project's repos (tags with a Release, newest first), read through the scm plugin group release and joined with the milestone and tasks named in the approval record docs/releases/<version>.md (or the top of the Release body when the record is kept there). Data comes from the task replica, so it follows the sync interval. Releases made outside Bandum have no record: they are listed with note: no_record and no numbers. An empty list also means the repo's scm plugin has no release group yet.
Release wait time (waitHours) is the time from the moment the release candidate was ready to the moment the tag was created: readyAt is the latest of the Approved time and the closing time of the release's tasks (a task is closed when its pull request merges; the replica has no separate merge time). Times after the tag are ignored, so the value is never negative. It is one segment of the Flow time of those tasks. It is not the DORA "lead time for changes" and the Portal does not call it that. AI cost per release (costUsd) is the sum of the AI cost of the release's tasks, joined through forge.issue like the cost per task; it is null when no task had an AI session (not a false 0). Both are measured per release, never per person.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
key | path | string | yes | |
limit | query | integer | Newest releases to return (default 20, at most 100) |
Responses
| Code | Description | Type |
|---|---|---|
| 200 | Releases | application/json · object |
| 401 | Missing or invalid token | application/problem+json · object |
| 403 | Forbidden | application/problem+json · object |
| 404 | Not found. Also returned for a project that exists but is private and the caller cannot see (never 403, so a private project cannot be discovered) | application/problem+json · object |
| 503 | Tara did not answer the check of which projects the caller can see (private projects). Ryoma never treats this as "sees everything"; retry after the Retry-After header (30 seconds) | application/problem+json · object |
Example response
{
"project": "string",
"total": 0,
"waitMedianHours": 0,
"waitP85Hours": 0,
"items": [
{
"repo": "string",
"tag": "v1.4.0",
"version": "1.4.0",
"sha": "string",
"at": "2026-11-01T00:00:00Z",
"tasks": 0,
"missingTasks": 0,
"lateTasks": 0,
"tasksWithAi": 0
}
]
}Call with curl
curl "https://ryoma.phillipcli.cloud/v1/projects/<key>/releases" \
-H "Authorization: Bearer $TARA_TOKEN"/v1/projects/{key}/baselineAdminFlow before and after the project started using AI (any role of the organization)
Compares the Flow numbers (velocity per week, flow time p50 and p85, flow efficiency, flow load) and the first-pass and rework rates of the N weeks before adoptedAt with the N weeks after it, from the synced task history. adoptedAt is the date set by an organization owner or admin, or, by default, the earlier of the first day Ryoma received telemetry for the project's repos and the project creation date (source: override, telemetry, created, none; none only when there is no project). before and after are absent while there is no adoptedAt. A metric with no samples is absent. warnings tell when the comparison is not reliable: before_sample_small (fewer than minSample = 10 finished tasks before), after_sample_small, after_window_short (adopted less than N weeks ago; compare per-week numbers), adoption_in_future, no_adoption_date. Measured per project, never per person; a correlation, not causation.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
key | path | string | yes | |
weeks | query | integer | Length of each period in weeks (the period before and the same length after adoptedAt) |
Responses
| Code | Description | Type |
|---|---|---|
| 200 | Settings and comparison | application/json · object |
| 400 | Invalid parameters | application/problem+json · object |
| 401 | Missing or invalid token | application/problem+json · object |
| 403 | Forbidden | application/problem+json · object |
| 404 | Not found. Also returned for a project that exists but is private and the caller cannot see (never 403, so a private project cannot be discovered) | application/problem+json · object |
| 503 | Tara did not answer the check of which projects the caller can see (private projects). Ryoma never treats this as "sees everything"; retry after the Retry-After header (30 seconds) | application/problem+json · object |
Example response
{
"project": "string",
"name": "string",
"weeks": 0,
"adoptedAt": "string",
"source": "telemetry",
"minSample": 0,
"warnings": [
{
"code": "no_adoption_date",
"message": "string"
}
]
}Call with curl
curl "https://ryoma.phillipcli.cloud/v1/projects/<key>/baseline" \
-H "Authorization: Bearer $TARA_TOKEN"/v1/projects/{key}/baselineAdminSet the date the project started using AI (org owner and admin)
Overrides the default (first telemetry). Only the calendar date is kept. Returns the new comparison.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
key | path | string | yes | |
weeks | query | integer | Length of each period in weeks (the period before and the same length after adoptedAt) |
Body (application/json)
| Field | Type | Required | Description |
|---|---|---|---|
adoptedAt | string (date) | yes | Date the project started using AI (YYYY-MM-DD), from 2020-01-01 |
Responses
| Code | Description | Type |
|---|---|---|
| 200 | Saved; the comparison with the new date | application/json · object |
| 400 | Invalid parameters | application/problem+json · object |
| 401 | Missing or invalid token | application/problem+json · object |
| 403 | Forbidden | application/problem+json · object |
| 404 | Not found. Also returned for a project that exists but is private and the caller cannot see (never 403, so a private project cannot be discovered) | application/problem+json · object |
| 503 | Tara did not answer the check of which projects the caller can see (private projects). Ryoma never treats this as "sees everything"; retry after the Retry-After header (30 seconds) | application/problem+json · object |
Example response
{
"project": "string",
"name": "string",
"weeks": 0,
"adoptedAt": "string",
"source": "telemetry",
"minSample": 0,
"warnings": [
{
"code": "no_adoption_date",
"message": "string"
}
]
}Call with curl
curl -X PUT "https://ryoma.phillipcli.cloud/v1/projects/<key>/baseline" \
-H "Authorization: Bearer $TARA_TOKEN" \
-H "Content-Type: application/json" \
-d '{"adoptedAt":"string"}'/v1/projects/{key}/baselineAdminGo back to the default adoption date, the first telemetry (org owner and admin)
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
key | path | string | yes | |
weeks | query | integer | Length of each period in weeks (the period before and the same length after adoptedAt) |
Responses
| Code | Description | Type |
|---|---|---|
| 200 | Reset; the comparison with the default date | application/json · object |
| 400 | Invalid parameters | application/problem+json · object |
| 401 | Missing or invalid token | application/problem+json · object |
| 403 | Forbidden | application/problem+json · object |
| 404 | Not found. Also returned for a project that exists but is private and the caller cannot see (never 403, so a private project cannot be discovered) | application/problem+json · object |
| 503 | Tara did not answer the check of which projects the caller can see (private projects). Ryoma never treats this as "sees everything"; retry after the Retry-After header (30 seconds) | application/problem+json · object |
Example response
{
"project": "string",
"name": "string",
"weeks": 0,
"adoptedAt": "string",
"source": "telemetry",
"minSample": 0,
"warnings": [
{
"code": "no_adoption_date",
"message": "string"
}
]
}Call with curl
curl -X DELETE "https://ryoma.phillipcli.cloud/v1/projects/<key>/baseline" \
-H "Authorization: Bearer $TARA_TOKEN"