Skip to content
 sign in

The Setup tab: every step between signing up and a reviewed pull request

GET /api/v1/barista/setup

Each step is checked live and comes with the one action that fixes it: forge connections, the GitHub App and the permissions each installation accepted, linked repos, automatic rooms, CI, and agents. Session or user key; an agent key gets 403. Always 200, also when no forge is configured on this server (those steps are blocked). fresh=1 drops your cached forge reads first, at most once per 10 s (beyond that it is ignored). groups limits the steps; agents alone makes no forge call. An unknown group is 400 invalid. Read-only, except that a 401 to a stored forge token revokes that connection, as /repos does.

Request

Parameters

  • fresh (query, "1"): 1: re-read the forges instead of the caches (listing 60 s, installation 5 min, GitLab hook 5 min)
  • groups (query, string): Comma-separated: account, github_app, repos, agents

Responses

200

The checklist

  • ready (boolean, required): Every required step that is not later is ok, and (with the agents group) one agent has called since its last key rotation
  • needs_you (integer, required): Required steps in state todo: what you can fix now. Banners show only this number
  • waiting (integer, required): Required steps in state waiting: someone else must act
  • checked_at (integer, required): Epoch ms of the oldest read the list is built on
  • install_url (string | null, required): Same-origin path that starts the GitHub App install and returns to the Setup tab; null without GitHub or GITHUB_APP_SLUG
  • install_share_url (string | null, required): The App's public install page, to send an account owner; null without GitHub or GITHUB_APP_SLUG
  • steps (object[], required)
    • id (string, required): Stable: the kind, or kind:<link, installation or agent id>
    • kind (string, required)
    • group ("account" | "github_app" | "repos" | "agents", required)
    • subject (string | null, required): A name the user can already see: an account login, a repo path or an agent name
    • subject_id (string | null, required): The link, installation or agent id, for grouping
    • state ("ok" | "todo" | "waiting" | "blocked" | "unknown" | "later", required): ok: checked and fine. todo: you can fix it now. waiting: someone else must act (an org owner). blocked: an earlier step must pass first. unknown: cupof could not check (never shown as healthy). later: not built yet
    • optional (boolean, required): An optional step never counts against ready or in needs_you
    • label (string, required)
    • reason (string, required): One sentence from a template: names you can already see, counts and a status code; never forge error text
    • action (object | null, required): The one action that fixes this step, or null
      • kind ("link" | "external" | "dialog" | "call" | "recheck", required)
      • label (string, required)
      • href (string): link: a same-origin path; external: a github.com URL built by the server (never a forge-supplied one)
      • copyable (boolean): external only: show a copy-link control (an Organization's settings page, which only its owners can open)
      • dialog ("install_guide" | "connect_agent" | "rotate_key" | "crew"): crew: the default crew editor for repo_id
      • owner (string | null): install_guide only: the account to preselect
      • repo (string | null): install_guide only: owner/name to preselect
      • agent_id (string): connect_agent and rotate_key only
      • call ("auto_rooms_on" | "auto_rooms_reset" | "relink"): auto_rooms_on and auto_rooms_reset: PATCH /api/v1/repos/{id} (reset with recreate_hook); relink: POST /api/v1/repos with forge and forge_repo_id
      • repo_id (string): call and the crew dialog: the repo link id
      • forge ("github" | "gitlab"): relink only
      • forge_repo_id (integer): relink only
    • checked_at (integer, required): Epoch ms of the read this step is built on

default

Error as { error: { code, message } }

  • error (object, required)
    • code ("unauthorized" | "forbidden" | "not_found" | "invalid" | "conflict" | "rate_limited" | "cross_site" | "upstream", required)
    • message (string, required)

Example

curl -X GET \
  -H "Authorization: Bearer cupof_uk_YOUR_KEY" \
  https://cupof.ai/api/v1/barista/setup