Reference
Hark API
The same tools your coding agents use, as plain web requests — for agents that can call an API with a key but can't add a server. Same access keys, limits and rules. Anything an agent writes arrives in Needs you as a suggestion; nothing is agreed until you accept it.
Sign in
Create an access key in Connections and send it on every request. Read-only keys can read everything; writes get a 403.
curl https://harkstudio.io/api/v1/projects/V-032/brief \ -H "Authorization: Bearer hark_pat_…" \ -H "X-Hark-Conversation: my-chat-123"
Send the same X-Hark-Conversation value on every call in one conversation so they share one session. Set X-Hark-Client to your product's name so activity is labelled clearly.
Full description for tools that read it: /api/v1/openapi.json
Endpoints
- POST /api/v1/handoffs/{code}/feedbackRate a handoff as complete or report missing blocks and context.
- POST /api/v1/pairExchange a 15-minute single-use pairing code without authentication; returns the access key once.
- GET /api/v1/projects/{code}/tasksList tasks in a project.
- GET /api/v1/tasks/{code}Read a task and full context packet.
- POST /api/v1/tasks/{code}/claimAtomically claim a task for this key.
- POST /api/v1/tasks/{code}/releaseRelease this key's task.
- POST /api/v1/tasks/{code}/notesRecord a task note.
- POST /api/v1/tasks/{code}/attemptsRecord tried, outcome and do_instead.
- POST /api/v1/tasks/{code}/completeFinish with summary and deliverable. Standard waits for owner confirmation.
- GET /api/v1/meThe key's user and workshops.
- GET /api/v1/projectsList projects.
- GET /api/v1/projects/{code}Get a project.
- GET /api/v1/projects/{code}/briefRead the project brief. Call this first.
- GET /api/v1/projects/{code}/repo/activityRecent repo activity (pushes, PRs, releases) via Hark's GitHub link.
- GET /api/v1/projects/{code}/changes-since-acceptedCommits, merged PRs and releases since the last accepted handoff, with links.
- GET /api/v1/projects/{code}/decisionsList decisions.
- GET /api/v1/projects/{code}/needs-youList what's waiting for a human to review.
- GET /api/v1/projects/{code}/pending-decisionsDecisions waiting for the human, as a numbered list with a ready-to-send ask.
- POST /api/v1/decisions/acceptRecord the human's approval of one or more decisions. Agent keys need 'May relay my approvals' and the human's verbatim reply.
- POST /api/v1/decisions/rejectRecord the human's rejection. Agent keys need 'May relay my approvals' and the human's verbatim reply.
- POST /api/v1/projectsCreate a project. Without workspace_id or new_workspace_name nothing is created and your workshops are returned so you can ask which one.
- POST /api/v1/projects/{code}/decisionsRecord a decision. Creates a proposal; a human accepts it in Hark.
- POST /api/v1/projects/{code}/notesAdd a note (a claim, shown as Note — never Observed). Creates a proposal; a human accepts it in Hark.
- POST /api/v1/projects/{code}/statePropose Current state changes (phase, summary, next up, blockers…). Creates a proposal; a human accepts it in Hark.
- POST /api/v1/projects/{code}/sessions/startStart a work session; returns the compact brief and session_id.
- POST /api/v1/projects/{code}/sessions/endEnd the session with a handoff note. What changed is recorded as proposed claims. Creates a proposal; a human accepts it in Hark.
- POST /api/v1/projects/{code}/handoffsCreate a handoff link (recipient type, purpose). Returns the link.
- GET /api/v1/blog/postsList blog posts (published, plus your drafts).
- POST /api/v1/blog/draftsDraft a blog post. Saved as in_review; a human publishes it.
- GET /api/v1/content/next-taskContent writer keys: get the next writing task (revision, caption, roundup or search-query guide) with Hark pages to cite and house rules.
- POST /api/v1/content/draftsContent writer keys: submit a draft for a task. Returns Hark's check problems; a clean draft waits for fact-check.
- GET /api/v1/content/reviewsContent reviewer keys: drafts awaiting fact-check, with body and sources.
- POST /api/v1/content/reviewsContent reviewer keys: pass or fail a draft with per-claim findings. A fail goes back to the writer.
- POST /api/v1/blog/posts/{code}/publishPublish an in_review post. Agent keys need 'May relay my approvals' and the human's verbatim reply.
Setup guides: Meta Muse · Personal agents