You can use the Evo Researcher public API to create and manage projects, templates, apps and chats from your own systems and integrations.

The Evo Researcher public API lets other Evo products and integrations work with Researcher from code. You can create projects, hand over conversations from other AI tools, and manage templates, apps, skills, collaborators and chats. This article explains how to get started and where to find each task.

Make sure you have the following before you make your first request.

A request from an inactive user or organisation returns 403. A missing or invalid token returns 401.

Choose the base URL for your environment, then add your token to each request.

All endpoint paths in this article are relative to your base URL. For example, POST /projects in Production UK is sent to the Production UK base URL followed by /projects.

Keep your button token secret. Store it in your integration's secure configuration, not in code that others can read.

You can create a project with only a name, or set up its template, instructions and chat history in one request.

Required conditions: Supply a name, a template_id, or both. If you leave out the name, you must supply a template_id, and Researcher names the project after the template with a timestamp.

If an AI chatbot passes a user to Researcher, send the conversation so far in the messages field. Each message needs a role of user or assistant, and content of up to 100,000 characters. Researcher sets the chat title from the first user message, so the user can carry on where they left off.

Templates provide the starting setup for a project, including its instructions, uploads, connectors and settings. A project takes a copy of its template when it is created, so editing a template does not change projects that already exist.

You cannot set a template's connectors, agents, knowledge spaces, actions or collaborators through the API. Configure these in Evo Researcher. Because updates never clear them, an update cannot remove this setup.

You can read your own personal templates through the API, but you cannot create, update or delete them there. Manage them in Evo Researcher.

An app is a template published to Navigator. It can appear as a Quick Panel, a Quick Action or a Quick Section, and it opens a focused Researcher experience. Apps start as drafts and go live only when you publish them.

Required conditions: Build each app on an organisation template. Use List Templates to find its id. A personal template id is rejected, because a published app is visible across the organisation.

Choose exactly one surface:

Set mobile to true if you also want the app in the Evo mobile app. It appears on desktop web only by default.

Choose one of these colours: teal, purple, nileblue, ceruleanblue, bluelagoon, eaglegreen, sapgreen, burntorange, brickred, accessred, electricviolet or blueviolet.

The params object controls how the app behaves:

A chatbot-style app usually turns off most features and leads with chat. A full-workspace app turns them on.

By default, a published app is visible to the whole organisation. To narrow access, set security to one of these:

Set one target only. You can set access on a draft, and it takes effect when you publish.

App fields use camelCase, such as quickAction and templateId. Projects and chats use snake_case, such as template_id.

Folders belong to the user who creates them, and you can nest them.

When you update a project, include only the fields you want to change.

Collaborators are existing Researcher users in your organisation. You choose whether each one can view the project or also change it.

Required conditions: You must own the project. To find a user's id, use GET /users, which needs the admin role.

A collaborator can remove themselves from a shared project. Anyone else needs the owner to remove them.

Your organisation's administrator sets a collaboration policy that limits sharing.

Existing collaborators keep their access if the policy changes, and you can always remove them.

A skill is a reusable set of instructions. Organisation skills belong to your whole organisation, and personal skills belong to you. Only skills with a binding type of project can be attached to a project.

Personal skills use the same paths under /skills/personal.

Attaching a skill that is already attached returns the existing attachment, so it is safe to repeat. Detaching a skill does not delete it from the library.

You can attach two types of connector through the API: Evo product connectors and third-party connectors. Agent and custom (MCP) connectors cannot be changed through the API.

Attaching a connector that is already attached on the same route returns 409.

Tags help you filter and organise projects. The API cannot list or create tags, so get the tag id from your own system.

Attaching a tag that is already attached, or removing one that is not, has no effect.

You can add files to a project and query spreadsheet data directly. Each file must be 30 MB or smaller.

Supported file types are .txt, .json, .csv, .md, .pdf, .docx, .xlsx, .xls, .pptx, .html, .xml, .rtf, .yaml, .yml and .log.

Use the download endpoint when your code needs the file itself. Use the blob-url endpoint for an iframe, an image or a link. Temporary links expire after about 5 minutes.

Spreadsheets become structured datasets. A CSV file produces one dataset, and an Excel file produces one dataset per sheet.

Each query works on a single dataset, and you cannot join datasets. A query returns 100 rows by default, up to 5,000 rows per response. If more rows exist, use the cursor from the response to get the next page.

Artifacts are the files and documents a project generates. Each artifact has one of these types: HTML, PDF, EXCEL, MARKDOWN, MFE, CHART or POWERPOINT.

To upload an artifact, send its name, its type and its content as base64. The limit is 30 MB.

The API stores the bytes you upload exactly as sent. It does not check that the file matches the type you declare.

PowerPoint artifacts do not support the blob-url endpoint. Use the download endpoint instead.

Use the start, poll and fetch pattern for background jobs, such as scheduled reports. Use streaming when a person is waiting for the reply.

To stop a chat that is still running, send a POST request to /projects/{projectId}/chats/{chatId}/cancel. Then check the status until it shows cancelled or idle.

While you check the status, watch message_count. When it goes up, a new reply has arrived.

Send a POST request to /projects/{projectId}/chats/stream with an id for the message and a message object that contains the role user and the text parts. The reply arrives as Server-Sent Events. If the connection drops, reconnect with GET /projects/{projectId}/chats/{chatId}/stream. This returns 204 when no stream is active.

To list the chats in a project, send GET /projects/{projectId}/chats.

Standalone chats sit outside a project, so they suit short, one-off conversations.

When you create a chat, every field is optional. You can add a name, a template_id, actions and messages. A chat can use one template only, and you cannot change it later.

Standalone chats have no transcript endpoint. You also cannot rename, delete or favourite them through the API.

A preset is a named model with the settings Researcher runs it with. Presets stay the same even when the model behind them changes, so your integration does not need to change.

A chat keeps the preset from its first turn, so you only need to set it once. If you ask for a preset you cannot use, the request returns 400 with the code PRESET_NOT_AVAILABLE. Researcher never swaps in a different preset. The older model field still works, but preset takes priority if you send both.

By default, chats started through the API approve every tool call they make. To pause write-type tool calls for approval, set enable_tool_consent to true when you start or stream a chat. Read-only calls are never paused. The setting is remembered for that chat.

Choosing always_allow approves future calls of the same tool and operation in that project, so Researcher stops asking.

If nobody answers a pending request within a few minutes, Researcher denies it automatically and the turn continues.

Use the LLM endpoints when you need one answer inside a wider workflow, such as classifying a support ticket or summarising a paragraph. Researcher stores nothing from these calls.

Both endpoints take the same body. Include a message, up to 100,000 characters. You can also add messages (earlier turns, up to 500), a system_prompt, a preset and tools.

To let the model search the web, set tools to an object with web_search set to true. Web search works only on presets whose model has built-in search. On any other preset, the request returns 400 with the code TOOL_NOT_AVAILABLE. Retry without web search, or choose a different preset.

Only admins can read other users' roles or grant and revoke them. Anyone can read their own roles by using me as the user id.

Granting a role the user already has, or revoking one they do not have, has no effect.

If your product embeds Researcher, your host can send messages into the open chat.

Researcher treats the message as if the user typed it. If a reply is still streaming, new messages queue and send in the order they arrived. Blank text is ignored. The call resolves once Researcher accepts the message, not when the reply finishes.