The API

Every endpoint lives under a single host. Paths are versioned with a /v1 prefix.

https://agentifys.ai

Authenticate every request with your project key as a Bearer token. Keys start with era_ and belong to one project. Create and rotate them in the admin under Settings.

Authorization: Bearer era_your_project_key

A missing or wrong key returns PROJECT_INVALID_KEY with a 401. Once the key resolves, most endpoints run the origin check described below.

A project carries a list of allowed origins, empty by default. While it is empty the check is skipped and any caller holding a valid key is served. The moment the list has one entry, every request to a checked endpoint must present a matching Origin header or it is refused with ORIGIN_NOT_ALLOWED and a 403.

The comparison is an exact string match on scheme + host + port, after any trailing slash is stripped from the incoming header. There are no wildcards and no subdomain matching. https://example.com does not admit https://www.example.com, and https://app.example.com does not admit https://app.example.com:8443. Add every origin you actually serve from.

https://app.example.com
https://www.example.com
http://localhost:5173

The check runs on /v1/chat, /v1/history, /v1/feedback, DELETE /v1/sessions/{id}, and every /v1/knowledge, /v1/scheduled-tasks, and /v1/oauth/mcp route. Two endpoints skip it: the vault (/v1/credentials, all three methods), which is server-to-server by design, and GET /v1/project-config, which the widget loads before anything else.

This is an application-level check, not a CORS restriction. CORS headers are permissive, so the browser will hand you the response rather than blocking it, and what you read is a 403 JSON body.

How you integrate decides what the allowlist should contain. Pick one per project.

Browser-direct. The embedded widget, or your own front-end code calling agentifys.ai from the page. Every request carries the page's origin. Fill the allowlist in: it is the only thing standing between your key and anyone who copies it out of your HTML.

Server-proxy. Your backend holds the key and calls Agentifys; the browser only ever talks to your server. Those requests arrive with no origin, so the allowed-origins list must be left empty. One entry is enough to break every call your backend makes. Access control in this shape is your own perimeter — the session or token your server already checks before it proxies.

Most endpoints take a user_context object that names the end user. This is what powers per-user memory, private knowledge, the vault, and scheduling.

A project runs in one of two identity modes. In open mode the identity is trusted as sent, good for personalization. In signed mode the identity is tamper-proof: you sign it server side with an HMAC secret, and that gates private uploads, the vault, per-user MCP OAuth, and the My-tasks panel.

Where the identity travels depends on the route, and the pattern is not guessable from the HTTP method. There is no fallback: a route reads exactly one location, and an identity sent anywhere else is treated as absent. This table is the whole matrix.

The X-Era-User header holds the same JSON, URL-encoded. Encode it even when the identity is pure ASCII: a raw JSON value is accepted, but a name with a non-Latin-1 character in it will be rejected by the browser before the request leaves.

X-Era-User: %7B%22id%22%3A%22u_42%22%2C%22_ts%22%3A1735689600%2C%22_sig%22%3A%22...%22%7D

Requests with a JSON body send Content-Type: application/json. Knowledge upload is the one exception, it is multipart/form-data.

Most responses are JSON. The chat endpoint is different: it always answers with text/event-stream (Server-Sent Events).

That is not negotiated. POST /v1/chat never reads your Accept header, and there is no way to ask it for a single JSON reply — whatever you send, the response is a stream you have to read to the end. The examples include the header below because it states what you expect, but sending it or omitting it makes no difference to what comes back.

Accept: text/event-stream

Each endpoint has its own page with request fields, responses, and copy-paste examples.

When something goes wrong, the response carries a stable error code. The full list lives on the errors reference.