Local API

The app is a Vue front end over a local HTTP API. You can call the same API from scripts. It isn’t versioned yet: endpoints may change between releases.

Authentication

The API answers only on 127.0.0.1 and localhost, and only requests with no cross-site Origin. Every /api request except /api/health needs the token from data/api-token, sent either as the relay_<port> cookie or in an X-Relay-Token header.

TOKEN=$(cat data/api-token)
curl -H "X-Relay-Token: $TOKEN" http://127.0.0.1:4318/api/projects

Errors are JSON: { "error": "…" } in plain words. A missing or wrong token returns 401 with "signIn": true.

Live feed

GET /api/feed is a server-sent events stream. Each data: line is a JSON message: event updates, connector status, action runs. A ping event arrives every 25 seconds; a stream that goes quiet past that is stale and should reconnect.

Endpoints

Events and approvals


`GET /api/events`	List events (All activity).
`GET /api/events/:id`	One event with its understanding, decision and replies.
`POST /api/events/:id/retry`	Retry a failed event.
`POST /api/events/:id/run`	Start the work for an event.
`POST /api/events/:id/respond`	Respond to an event.
`POST /api/events/:id/send`	Send a drafted reply.
`POST /api/approvals/:id`	Approve or reject.
`GET /api/events/:id/attachments/:attachmentId`	Attachment details.
`GET /api/events/:id/attachments/:attachmentId/contents`	Attachment file.

Chat and uploads


`POST /api/chat`	Send a chat message to a workspace.
`POST /api/uploads`	Upload a file for a chat message.
`DELETE /api/uploads/:id`	Remove an upload.
`GET /api/chat-titles`, `PUT /api/chat-titles`	Chat titles.

Workspaces and files


`GET /api/projects`, `POST /api/projects`	List or create workspaces.
`PUT /api/projects/:id`, `DELETE /api/projects/:id`	Update or delete a workspace.
`GET /api/projects/:id/files`	List files.
`GET /api/projects/:id/find`	Search files.
`GET /api/projects/:id/file`, `…/file/contents`	One file and its contents.
`GET /api/projects/:id/shared`	Files that came with the workspace’s messages, newest first.
`GET /api/projects/:id/targets`	Detected apps in the workspace’s repos.
`GET /api/projects/:id/icons`, `…/icon`, `…/icon-file`	Workspace icons.
`POST /api/files/open`	Open a file on this computer.

Actions


`GET /api/actions`	Every workspace’s actions.
`GET /api/projects/:id/actions`, `POST /api/projects/:id/actions`	A workspace’s actions; create one.
`GET /api/projects/:id/actions/config`	The repo’s `arkinsta.yaml` actions and errors.
`GET /api/projects/:id/actions/suggestions`	Suggested actions.
`PUT /api/actions/:actionId`, `DELETE /api/actions/:actionId`	Update or delete.
`POST /api/actions/:actionId/review`	Mark an `arkinsta.yaml` action as reviewed.
`POST /api/actions/:actionId/run`	Run it.
`GET /api/actions/:actionId/yaml`	The action as YAML.
`GET /api/actions/:actionId/runs`	Its runs.
`GET /api/action-runs`	Active and recent runs.
`GET /api/action-runs/:runId`, `…/log`	One run and its log.
`POST /api/action-runs/:runId/stop`	Stop a run.
`POST /api/action-runs/:runId/reveal`	Show a run’s output in Finder.

Settings, keys and credentials


`GET /api/settings`, `PUT /api/settings`	Settings.
`GET /api/secrets`, `PUT /api/secrets`	Which keys are set (never their values); set keys.
`GET /api/credentials`, `POST /api/credentials`	Store credentials.
`PUT /api/credentials/:id`, `DELETE /api/credentials/:id`
`POST /api/credentials/:id/check`	Check a credential with its store.

Setup and connections


`GET /api/setup`	The setup checklist.
`GET /api/setup/export`, `POST /api/setup/import`	Export and import.
`GET /api/setup/slack-manifest`, `…/slack-create-url`, `POST …/slack-check`	Slack bot setup.
`GET /api/connectors`	Connector status.
`POST /api/connectors/:source/check`	Check now.
`POST /api/connectors/:source/restart`	Restart a connector.
`GET /api/connectors/:source/containers`	Channels, teams and lists that can be linked to a workspace.
`GET /api/harnesses`	Agent tools found on this computer.
`GET /api/mcp`	Slack, Linear and ClickUp connections found in other tools.
`GET /api/models/:provider`, `GET /api/efforts/:provider`	Models and reasoning efforts for a provider.
`GET /api/folders/suggestions`, `…/check`, `…/checks`, `POST …/choose`	Repo folders.

Other


`GET /api/health`	`{ ok, busy }`. No token needed.
`GET /api/activity`	The activity log (Settings → Log).
`GET /api/usage`	Today’s tokens and cost, the budget, and the last 14 days.
`GET /api/views`, `POST`, `PATCH /api/views/:id`, `DELETE`	Saved activity views.