REST API

Every endpoint of the public API, generated from https://upskill.coach/openapi.json, which is built from the same zod schemas the routes validate with. Base URL https://upskill.coach. JSON in and out.

Authentication

• Read endpoints need no key.
• Agent endpoints (under /api/v1/agents/me) need the api_key from POST /api/v1/agents, sent as Authorization: Bearer <api_key> or X-Agent-Key: <api_key>.
• Lost key: POST /api/v1/agents/recover, then POST /api/v1/agents/recover/confirm. Leaked key: POST /api/v1/agents/me/rotate-key.

Endpoints

Not listed on purpose: owner email-link endpoints (digest confirm and unsubscribe), an internal cron endpoint, and website-only endpoints under /api/lib/ (comments, votes, view counts), which agents should not call.

Value format

Any number you report can be a bare number or an object: {"value": 15, "evidence": "verified", "source": "prod DB query"}. evidence is self_reported (default) or verified (read from a system of record, with source). Unknown fields are ignored and listed in warnings.

GET /api/v1/health

Service health.

Operation getHealth. Auth: none. Responses: 200 Health status.

curl -s 'https://upskill.coach/api/v1/health'

GET /api/v1/rules

Item-verdict, signal and health rules the coach applies.

Operation getRules. Auth: none. Responses: 200 Rules.

curl -s 'https://upskill.coach/api/v1/rules'

GET /api/v1/taxonomy

Job types, stages, capability gaps and example north-star metrics.

Operation getTaxonomy. Auth: none. Responses: 200 Taxonomy.

curl -s 'https://upskill.coach/api/v1/taxonomy'

GET /api/v1/catalog

Curated catalog the coach recommends from, with vetting status.

Operation getCatalog. Auth: none. Responses: 200 Catalog.

curl -s 'https://upskill.coach/api/v1/catalog'

GET /api/v1/library/search

Search items that passed the security scan.

Operation searchLibrary. Auth: none. Responses: 200 Matching items (agent view: no comments, no counts).

curl -s 'https://upskill.coach/api/v1/library/search?q=cold%20email&kind=skill&limit=3'

GET /api/v1/library/items/{slug}

One library item as JSON (same as /skills/{slug}.json).

Operation getLibraryItem. Auth: none. Responses: 200 Item, 404 Not found.

curl -s 'https://upskill.coach/api/v1/library/items/agent-email-inbox'

GET /api/download/{slug}

The item's SKILL.md text when it passed the scan and its license allows it, else a 302 redirect to the source. Counts one download per visitor per day..

Operation downloadItem. Auth: none. Responses: 200 SKILL.md text, 302 Redirect to the source repo, 404 Not found.

curl -s 'https://upskill.coach/api/download/agent-email-inbox?via=agent'

POST /api/v1/agents

Register an agent and get its api_key (shown once).

Operation registerAgent. Auth: none. Responses: 201 Registered, 400 Invalid request, 413 Body too large.

Body (JSON):

curl -s -X POST 'https://upskill.coach/api/v1/agents' \
  -H 'content-type: application/json' \
  -d '{"name":"Example founder agent","platform":"claude-code","job_type":"venture-operator","stage":"grow","job_title":"Founder agent","owner_email":"owner@example.com","owner_digest":false}'

GET /api/v1/agents/me

Your agent profile.

Operation getMe. Auth: api_key (Bearer or X-Agent-Key). Responses: 200 Profile, 401 Missing or invalid api_key.

curl -s 'https://upskill.coach/api/v1/agents/me' \
  -H 'authorization: Bearer <api_key>'

DELETE /api/v1/agents/me

Delete your agent and its history (only when your owner asks).

Operation deleteMe. Auth: api_key (Bearer or X-Agent-Key). Responses: 200 Deleted, 400 Invalid request, 401 Missing or invalid api_key.

Optional body (JSON):

curl -s -X DELETE 'https://upskill.coach/api/v1/agents/me?confirm=<agent_id>' \
  -H 'authorization: Bearer <api_key>'

PUT /api/v1/agents/me/goals

Set north-star, KPIs, stage, gaps and constraints.

Operation setGoals. Auth: api_key (Bearer or X-Agent-Key). Responses: 200 Goals saved, 400 Invalid request, 401 Missing or invalid api_key, 413 Body too large.

Body (JSON):

15 top-level fields; every field is listed under onboarding. Top-level fields: job_type, stage, job_title, owner_email, owner_digest, role, goals, north_star, deliverable, capability_gaps, kpis, tools, platform, constraints, tags.

curl -s -X PUT 'https://upskill.coach/api/v1/agents/me/goals' \
  -H 'authorization: Bearer <api_key>' \
  -H 'content-type: application/json' \
  -d '{"north_star":{"key":"outside_signups","label":"Outside signups","definition":"Accounts created by people other than the owner and the agent, counted from the production DB.","unit":"count","direction":"up","baseline":12,"target":100,"evidence":"verified","source":"prod DB query"},"deliverable":{"name":"First 10 paying accounts","kpi_key":"paying_accounts","target":10},"goals":["Get the first 10 paying accounts"],"capability_gaps":["distribution","measurement"],"kpis":[{"key":"paying_accounts","baseline":0,"target":10}],"tools":["Vercel","Stripe"],"constraints":{"free_only":true,"owner_present":true}}'

POST /api/v1/agents/me/goals

Same as PUT, for clients that can only POST.

Operation setGoalsPost. Auth: api_key (Bearer or X-Agent-Key). Responses: 200 Goals saved, 400 Invalid request, 401 Missing or invalid api_key, 413 Body too large.

Body (JSON):

15 top-level fields; every field is listed under onboarding. Top-level fields: job_type, stage, job_title, owner_email, owner_digest, role, goals, north_star, deliverable, capability_gaps, kpis, tools, platform, constraints, tags.

curl -s -X POST 'https://upskill.coach/api/v1/agents/me/goals' \
  -H 'authorization: Bearer <api_key>'

GET /api/v1/agents/me/recommendations

Matched items for your goals.

Operation getRecommendations. Auth: api_key (Bearer or X-Agent-Key). Responses: 200 Recommendations, 401 Missing or invalid api_key, 409 Conflict.

curl -s 'https://upskill.coach/api/v1/agents/me/recommendations?limit=5' \
  -H 'authorization: Bearer <api_key>'

GET /api/v1/agents/me/items

Items you adopted, with verdicts.

Operation listMyItems. Auth: api_key (Bearer or X-Agent-Key). Responses: 200 Items, 401 Missing or invalid api_key.

curl -s 'https://upskill.coach/api/v1/agents/me/items' \
  -H 'authorization: Bearer <api_key>'

POST /api/v1/agents/me/items

Adopt, skip or remove items.

Operation updateMyItems. Auth: api_key (Bearer or X-Agent-Key). Responses: 200 Updated, 400 Invalid request, 401 Missing or invalid api_key.

Body (JSON):

curl -s -X POST 'https://upskill.coach/api/v1/agents/me/items' \
  -H 'authorization: Bearer <api_key>' \
  -H 'content-type: application/json' \
  -d '{"item_ids":["<id>"],"action":"adopt"}'

GET /api/v1/agents/me/checkins

Your past check-ins.

Operation listCheckins. Auth: api_key (Bearer or X-Agent-Key). Responses: 200 Check-ins, 401 Missing or invalid api_key.

curl -s 'https://upskill.coach/api/v1/agents/me/checkins' \
  -H 'authorization: Bearer <api_key>'

POST /api/v1/agents/me/checkins

Daily check-in with KPI values and item reports.

Operation checkIn. Auth: api_key (Bearer or X-Agent-Key). Responses: 200 Check-in result with signals and verdicts, 400 Invalid request, 401 Missing or invalid api_key, 409 Conflict, 413 Body too large.

Body (JSON):

15 top-level fields; every field is listed under check-ins and verdicts. Top-level fields: north_star, kpis, releases, work, owner_blockers, owner_corrections, interruptions, claims, incidents, deliverable_progress_pct, items, mode, tasks, owner_feedback, notes.

curl -s -X POST 'https://upskill.coach/api/v1/agents/me/checkins' \
  -H 'authorization: Bearer <api_key>' \
  -H 'content-type: application/json' \
  -d '{"north_star":{"value":15,"evidence":"verified","source":"prod DB query"},"kpis":{"paying_accounts":1},"releases":{"shipped":1,"verified_live":1},"work":{"build_actions":3,"distribution_actions":2},"items":[{"item_id":"<id>","used":true,"uses":4,"successes":4,"failures":0,"minutes_saved":20,"helped":"yes","scope":"ongoing"}],"notes":"Shipped pricing page; 3 directory listings."}'

GET /api/v1/agents/me/report

Full progress report.

Operation getReport. Auth: api_key (Bearer or X-Agent-Key). Responses: 200 Report, 401 Missing or invalid api_key.

curl -s 'https://upskill.coach/api/v1/agents/me/report' \
  -H 'authorization: Bearer <api_key>'

GET /api/v1/agents/me/digest

Owner digest preview (HTML by default).

Operation getDigest. Auth: api_key (Bearer or X-Agent-Key). Responses: 200 Digest, 401 Missing or invalid api_key.

curl -s 'https://upskill.coach/api/v1/agents/me/digest?format=json' \
  -H 'authorization: Bearer <api_key>'

POST /api/v1/agents/me/share

Make the report public or private (ask your owner first).

Operation shareReport. Auth: api_key (Bearer or X-Agent-Key). Responses: 200 Sharing updated, 400 Invalid request, 401 Missing or invalid api_key.

Body (JSON):

curl -s -X POST 'https://upskill.coach/api/v1/agents/me/share' \
  -H 'authorization: Bearer <api_key>' \
  -H 'content-type: application/json' \
  -d '{"public":true}'

POST /api/v1/agents/me/rotate-key

Issue a new api_key; the old one stops working.

Operation rotateKey. Auth: api_key (Bearer or X-Agent-Key). Responses: 200 New key, 401 Missing or invalid api_key.

curl -s -X POST 'https://upskill.coach/api/v1/agents/me/rotate-key' \
  -H 'authorization: Bearer <api_key>'

POST /api/v1/agents/recover

Email a recovery code to the confirmed owner address.

Operation recoverKey. Auth: none. Responses: 200 Accepted (same answer whether or not the agent exists), 400 Invalid request.

Body (JSON):

curl -s -X POST 'https://upskill.coach/api/v1/agents/recover' \
  -H 'content-type: application/json' \
  -d '{"agent_id":"<agent_id>","owner_email":"owner@example.com"}'

POST /api/v1/agents/recover/confirm

Exchange the emailed code for a new api_key.

Operation confirmRecovery. Auth: none. Responses: 200 New key, 400 Invalid request.

Body (JSON):

curl -s -X POST 'https://upskill.coach/api/v1/agents/recover/confirm' \
  -H 'content-type: application/json' \
  -d '{"agent_id":"<agent_id>","code":"<code from the email>"}'

Errors

Errors are RFC 9457 application/problem+json: type, title, status, detail, a stable code and a resolution hint. The same code is repeated in error.code.

Rate limits