Log in

API Reference

REST API for integrating with the Headways platform.

The Headways API allows you to programmatically interact with the platform. All endpoints require authentication via API key.

Base URL

https://api.headways.ai/v1

Authentication

Include your API key in the Authorization header:

curl -H "Authorization: Bearer hw_your_api_key" \
  https://api.headways.ai/v1/me

API keys are managed under Settings > API Keys in the dashboard.

Error Responses

All errors follow a consistent format:

{
  "error": {
    "code": "invalid_request",
    "message": "The request body is missing the required 'email' field.",
    "status": 400
  }
}
StatusCodeDescription
400invalid_requestMalformed request
401unauthorizedMissing or invalid API key
403forbiddenInsufficient permissions
404not_foundResource does not exist
429rate_limitedToo many requests
500internal_errorServer error

Endpoints

Me

MethodPathDescription
GET/meGet the current user
GET/me/installsList skills installed by this user

Skills

MethodPathDescription
GET/skillsList skills in the org
POST/skillsCreate a new skill
GET/skills/:slugGet skill details
PATCH/skills/:slugUpdate skill metadata
DELETE/skills/:slugArchive a skill
POST/skills/importImport a skill from a file
GET/skills/:slug/draftGet the current draft
PATCH/skills/:slug/draftUpdate draft content
GET/skills/:slug/versionsList all published versions
GET/skills/:slug/feedbackList feedback on a skill
POST/skills/:slug/feedbackSubmit feedback on a skill
GET/skills/:slug/installsGet install count and stats
GET/skills/:slug/activityGet activity log for a skill

Skill Lifecycle

MethodPathDescription
POST/skills/:slug/versions/:v/submitSubmit a draft version for review
POST/skills/:slug/versions/:v/approveApprove a submitted version
POST/skills/:slug/versions/:v/rejectReject a submitted version
POST/skills/:slug/versions/:v/publishPublish an approved version
POST/skills/:slug/versions/:v/sample-runRecord a sample run for a version

Protection Rules

MethodPathDescription
GET/orgs/me/protection-rulesGet org-level protection rules
PUT/orgs/me/protection-rulesUpdate org-level protection rules
GET/skills/:slug/protection-rulesGet skill-level protection rule overrides
PUT/skills/:slug/protection-rulesUpdate skill-level rule overrides

Org Activity

MethodPathDescription
GET/orgs/me/activityOrg-level audit log
GET/orgs/me/audit/exportExport full audit log (CSV)

Insights

MethodPathDescription
GET/insights/overviewAggregate skill run counts
GET/insights/skillsPer-skill run stats
GET/insights/skills/:slugRun stats for a specific skill

Connections

MethodPathDescription
GET/connectionsList MCP connections for this user
POST/connectionsCreate a new MCP connection
DELETE/connections/:idRemove a connection

Connectors

MethodPathDescription
GET/connectorsList available connector types