The HTTP API

Authentication

Every request carries a workspace API key as a bearer token. Create one in the console; the secret is shown once and is never stored in a form we can read back, so if you lose it, issue another and revoke the old one.

A key belongs to a workspace and can be pinned to a single employee. A pinned key that tries to address a different employee is refused, and no key ever reaches another workspace.

Authorization: Bearer emp_<workspace>_<secret>

Giving it a task

One POST with the employee id and what you want done, in plain language. Omit the chat id to start a new thread, or pass one to continue an existing conversation, which is what you want when a system is reporting repeatedly about the same thing.

curl -X POST https://employees.sanafai.com/api/v1/messages \
  -H "Authorization: Bearer $SANAF_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "employeeId": "…", "text": "Chase the three invoices that went past due today." }'

Why the answer is 202

A turn is durable. It can run for minutes, and it can pause for its manager approval for days. There is no honest way to return the finished reply on the same request, so the API does not pretend to.

You get back the chat id and the run id immediately. Read the reply with the MCP get_reply tool, or let the hire post the result where it normally would: the thread in Slack or Microsoft Teams, or the console.

{
  "employeeId": "…",
  "chatId": "…",
  "runId": "…",
  "status": "working"
}

Errors

A missing or invalid key is 401. A key that is pinned to one employee addressing another is 403. An employee id that does not exist in your workspace is 404, including a malformed id, because from the caller side those are the same thing. A body that is not JSON, or a request with no text, is 400 with a message that says which.

Endpoint reference