[epanonymous]

Fix the agent API docs to match the live API.

• All agent register/status examples and reference rows now use /v1/agents/* (bare paths return 404).
• Register examples generate a client_id once and reuse it; no shared hard-coded value. Added a note that client_id is a secret recovery credential.
• Request/response examples match the current register contract (201 new agent, 200 recovery retry).
• Fixed badges and links that pointed to a non-existent docs repo; package name is @deva-me/agent-sdk.

[claude]

Claude finished @epanonymous's task —— View job

---

Claude Code Review

• Read changed files
• Review path consistency (/v1/agents/*)
• Review client_id handling & security notes
• Review example files (python/typescript)
• Check links/badges & package name
• Post review feedback

---

Overall this is a solid, well-targeted docs fix. The /v1/agents/* path corrections are applied consistently, the client_id security framing is excellent, and the register contract (201 new / 200 recovery) is now accurate. Below are the issues I found, ordered by severity.

Bugs / correctness (should fix)

1. Web Search price is inconsistent across three files.

   • README.md:130 — table lists Web Search at 10 ₭ / $0.01
   • docs/pricing.md:24 — lists 5 ₭ / $0.005
   • docs/api-reference.md:167 — note says 5 ₭ per search
   • README.md:29 (platform coverage bullet) — says 5 ₭ per search

   So the README contradicts itself (10 ₭ in the table vs 5 ₭ in the bullet) and contradicts pricing.md. Pick one value and make all four spots agree.

2. Web Search status conflicts. docs/api-reference.md:165 marks POST /v1/agents/resources/search as unavailable, but docs/pricing.md:103 says Status: available. Since this PR is about matching the live API, these should be reconciled.

3. Chat model id doesn't match the repo's current model. Examples use anthropic/claude-opus-4-7 (README.md:67, docs/api-reference.md:257, docs/quickstart.md:51,68,85,100), but the most recent repo change (commit c4812a5) reverted the active model to claude-opus-4-8. If claude-opus-4-7 is no longer a valid catalog id, these copy-paste examples would 400. Worth confirming the intended example model id. (Out of this PR's stated scope, but directly affects the "match the live API" goal.)

Consistency nits (nice to fix while here)

4. Messaging request body differs between docs. docs/quickstart.md:174 sends {"to","subject","body"}, while the cron example in docs/api-reference.md:449-452 uses {"to","content"} for /v1/agents/messages/send. One of these field sets is wrong for the same endpoint — align them.

5. name regex vs. length rules are stated two ways. docs/api-reference.md:33 says 3-30 chars, ^[a-zA-Z0-9_]+$, while README.md:58/quickstart.md:36 phrase it as "letters/digits/underscore". That's fine, but the register JSON examples use my_agent_01 (11 chars) — good, just make sure the 3-30 bound is the authoritative one everywhere.

6. Register example comment duplication. The "JSON body read from stdin so client_id never appears in process arguments" note and the heredoc pattern are duplicated verbatim in README.md:45-56 and quickstart.md:23-34. Not wrong, but a single canonical spot (api-reference) that the others link to would reduce drift — this PR already shows how easily values drift (see chore: bump claude model to current pinned ids #1).

Security (positive + one note)

• Strong improvement: generating client_id via openssl rand -hex 32, keeping it out of argv via stdin heredoc, and the explicit "secret recovery credential" callouts (README.md:43, api-reference.md:64, quickstart.md:21) are exactly right.
• Minor: the regex allows - and _ (^[A-Za-z0-9_-]+$) but openssl rand -hex 32 only produces [0-9a-f] (64 chars). That's within bounds, just note users who pick a shorter custom id must respect the 32-char minimum.

Links / badges

• @deva-me/agent-sdk and the Deva-me-AI/deva-agent-sdk repo link are now consistent in README.md:112 and quickstart.md:206.
• Suggest verifying the deva-agent-sdk repo link resolves (can't fetch from here) since the PR title calls out dead repo links.

Performance / Test coverage

• N/A — documentation + example snippets only; no runtime code paths or test suite involved. The Python (httpx) and TS (fetch) examples look correct and include timeouts / error handling.

The most important items are #1–#3 (user-facing price/model mismatches that would mislead or break copy-paste usage). The rest are polish.
· fix/v1-agents-paths