Skip to content

API Ryoma: projects ​

Projects and their repos

This page is generated from openapi.yaml by npm run gen, so do not edit it by hand. Authentication is described on the overview page.

GET/v1/projectsAdmin

Projects 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 ​

CodeDescriptionType
200List of projectsapplication/json · object
401Missing or invalid tokenapplication/problem+json · object
503Tara 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 ​

json
{
  "items": [
    {
      "key": "string",
      "scm": {},
      "name": "string",
      "org": "string",
      "repos": [],
      "contacts": []
    }
  ]
}

Call with curl ​

bash
curl "https://ryoma.phillipcli.cloud/v1/projects" \
  -H "Authorization: Bearer $TARA_TOKEN"
PUT/v1/projects/{key}Admin

Set 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 ​

NameInTypeRequiredDescription
keypathstringyes

Body (application/json) ​

FieldTypeRequiredDescription
namestringOptional; must equal the current name (it comes from Tara)
reposstring[]Optional; must equal the project's current repos (they come from Tara)
contactsstring[]Email addresses that receive the project's risk alerts and weekly digest (PM); empty means they only go to the shared channel

Responses ​

CodeDescriptionType
200Project savedapplication/json · object
400Invalid parametersapplication/problem+json · object
401Missing or invalid tokenapplication/problem+json · object
403Forbiddenapplication/problem+json · object
404Not 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
503Tara 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 ​

json
{
  "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 ​

bash
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"]}'
DELETE/v1/projects/{key}Admin

Not 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 ​

NameInTypeRequiredDescription
keypathstringyes

Responses ​

CodeDescriptionType
401Missing or invalid tokenapplication/problem+json · object
403Forbiddenapplication/problem+json · object
404Not 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
503Tara 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 ​

bash
curl -X DELETE "https://ryoma.phillipcli.cloud/v1/projects/<key>" \
  -H "Authorization: Bearer $TARA_TOKEN"
GET/v1/projects/{key}/qualityAdmin

Data 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 ​

NameInTypeRequiredDescription
keypathstringyes

Responses ​

CodeDescriptionType
200Warnings (empty list when the data is in good shape)application/json · object
401Missing or invalid tokenapplication/problem+json · object
403Forbiddenapplication/problem+json · object
404Not 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
503Tara 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 ​

json
{
  "project": "string",
  "checkedAt": "2026-11-01T00:00:00Z",
  "warnings": [
    {
      "code": "type_coverage_low",
      "message": "string",
      "count": 0,
      "total": 0,
      "fix": {}
    }
  ]
}

Call with curl ​

bash
curl "https://ryoma.phillipcli.cloud/v1/projects/<key>/quality" \
  -H "Authorization: Bearer $TARA_TOKEN"
GET/v1/projects/{key}/releasesAdmin

Releases 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 ​

NameInTypeRequiredDescription
keypathstringyes
limitqueryintegerNewest releases to return (default 20, at most 100)

Responses ​

CodeDescriptionType
200Releasesapplication/json · object
401Missing or invalid tokenapplication/problem+json · object
403Forbiddenapplication/problem+json · object
404Not 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
503Tara 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 ​

json
{
  "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 ​

bash
curl "https://ryoma.phillipcli.cloud/v1/projects/<key>/releases" \
  -H "Authorization: Bearer $TARA_TOKEN"
GET/v1/projects/{key}/baselineAdmin

Flow 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 ​

NameInTypeRequiredDescription
keypathstringyes
weeksqueryintegerLength of each period in weeks (the period before and the same length after adoptedAt)

Responses ​

CodeDescriptionType
200Settings and comparisonapplication/json · object
400Invalid parametersapplication/problem+json · object
401Missing or invalid tokenapplication/problem+json · object
403Forbiddenapplication/problem+json · object
404Not 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
503Tara 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 ​

json
{
  "project": "string",
  "name": "string",
  "weeks": 0,
  "adoptedAt": "string",
  "source": "telemetry",
  "minSample": 0,
  "warnings": [
    {
      "code": "no_adoption_date",
      "message": "string"
    }
  ]
}

Call with curl ​

bash
curl "https://ryoma.phillipcli.cloud/v1/projects/<key>/baseline" \
  -H "Authorization: Bearer $TARA_TOKEN"
PUT/v1/projects/{key}/baselineAdmin

Set 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 ​

NameInTypeRequiredDescription
keypathstringyes
weeksqueryintegerLength of each period in weeks (the period before and the same length after adoptedAt)

Body (application/json) ​

FieldTypeRequiredDescription
adoptedAtstring (date)yesDate the project started using AI (YYYY-MM-DD), from 2020-01-01

Responses ​

CodeDescriptionType
200Saved; the comparison with the new dateapplication/json · object
400Invalid parametersapplication/problem+json · object
401Missing or invalid tokenapplication/problem+json · object
403Forbiddenapplication/problem+json · object
404Not 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
503Tara 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 ​

json
{
  "project": "string",
  "name": "string",
  "weeks": 0,
  "adoptedAt": "string",
  "source": "telemetry",
  "minSample": 0,
  "warnings": [
    {
      "code": "no_adoption_date",
      "message": "string"
    }
  ]
}

Call with curl ​

bash
curl -X PUT "https://ryoma.phillipcli.cloud/v1/projects/<key>/baseline" \
  -H "Authorization: Bearer $TARA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"adoptedAt":"string"}'
DELETE/v1/projects/{key}/baselineAdmin

Go back to the default adoption date, the first telemetry (org owner and admin)

Parameters ​

NameInTypeRequiredDescription
keypathstringyes
weeksqueryintegerLength of each period in weeks (the period before and the same length after adoptedAt)

Responses ​

CodeDescriptionType
200Reset; the comparison with the default dateapplication/json · object
400Invalid parametersapplication/problem+json · object
401Missing or invalid tokenapplication/problem+json · object
403Forbiddenapplication/problem+json · object
404Not 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
503Tara 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 ​

json
{
  "project": "string",
  "name": "string",
  "weeks": 0,
  "adoptedAt": "string",
  "source": "telemetry",
  "minSample": 0,
  "warnings": [
    {
      "code": "no_adoption_date",
      "message": "string"
    }
  ]
}

Call with curl ​

bash
curl -X DELETE "https://ryoma.phillipcli.cloud/v1/projects/<key>/baseline" \
  -H "Authorization: Bearer $TARA_TOKEN"