Why does recording a finding from my outside agent in a project return 409?

Tares returns 409 when the project key you use to record a finding is named like one of the instance’s Tares agents. Give the key another name and the finding records. The key’s name is the agent name the finding carries, so pick a name that says who holds the key.

How it works

A project can have project keys for agents that run outside Tares, such as Claude Code, Codex or your own service. A project key reads one project and records findings in it, and nothing else.

When the outside agent calls POST /api/projects/{id}/findings, Tares stores the finding like a Tares agent’s finding and stamps it with the key’s name as its agent. That is why the name matters:

• A key named like one of the instance’s Tares agents cannot record findings. The call answers 409.
• A key with any other name records findings under that name.
• The finding lands on the entity’s timeline, every later read of the entity includes it, and a trigger over the findings source can fire on it.
• It shows as a card under What the agents found on the Overview. In Advanced setup’s Activity it is a thread marked as recorded from outside Tares.

This is separate from the 403 a project key returns for anything other than reading its project and recording findings.

Set it up

1. Open the project page and go to Advanced setup, then Settings → Keys.
2. Find the key that gets 409. Check whether its name matches one of your Tares agents, which you can see in the project’s Agents section.
3. Revoke that key with Revoke, which cuts the agent off.
4. Make a new key and name it after who holds it, for example claude-code-laptop. Copy the secret, which is shown once.
5. Update your outside agent to use the new secret.
6. Record the finding again. The body takes entity and finding, plus the optional verdict, label, headline and next_step:

{ "entity": "checkout", "finding": "Errors began after deploy 9f2c81d ...", "verdict": "rca", "label": "service" }

7. Check the result. List the project’s findings with GET /api/projects/{id}/findings?entity=&agent=&limit=. Your finding carries the new key name as its agent and external: true.

Project keys are checked on a secured instance, one with TARES_AUTH_TOKEN. On an open instance there are no keys to hand out, and the MCP tools take the project by name.

What you get

• The finding records in the project instead of returning 409.
• Your findings carry a name you chose, so you can tell at a glance which outside agent wrote what. Filter the findings list by agent to see one agent’s findings.
• Outside findings sit on the same timelines as the Tares agents’ findings, and the findings list marks each one external: true or false.
• Triggers over the findings source can fire on what your outside agent records.
• Other keys keep working, because renaming applies to the one key you replace.

When something else fits

If the call returns 403 instead of 409, the key is being used for something other than reading its project and recording findings, so use it only for those. For the full walkthrough of connecting Claude Code to a project, see the guide on connecting an outside agent. To see how projects fit into a monitoring setup, start from AI SRE.

Related