docs: fix OpenAPI server URL and stop teaching API-key project CRUD

[duyetbot]

Summary

Fixes docs/spec drift from #411 (no new features).

• OpenAPI servers is now https://agentstate.app so paths /api/v1/* are not doubled to /api/api/v1/*.
• agents.md / llms.txt / regenerated static.ts no longer teach API-key POST/GET /api/v1/projects. Project CRUD is Clerk/dashboard only; those routes 401 with a Bearer API key. /v1/projects is not mounted.
• Pagination docs use the live shape { data, pagination: { limit, next_cursor } } in agents.md and the worst-wrong sections of docs/api-reference.md.
• Conversation update is already PUT in these files (no remaining PATCH /conversations claim). docs: README and api-reference say conversation update uses PATCH; the route is actually PUT #301 / [docs] Conversation update documented as PATCH but route is PUT #332 were already corrected in-tree.

Also closes #333 on the same project-docs: paths are /api/v1/projects/* only.

Test plan

• Confirm OpenAPI servers[0].url is https://agentstate.app and a generated client would call https://agentstate.app/api/v1/conversations
• Confirm /agents.md and /llms.txt do not show Authorization: Bearer as_live_... against POST /api/v1/projects
• Confirm conversation/message list docs show { data, pagination: { limit, next_cursor } } (no top-level has_more, no pagination.total on those lists)
• Confirm docs/api-reference.md project CRUD is marked Clerk/dashboard and says /v1/projects is not mounted

Closes #411
Closes #333

Summary by Sourcery

Align API documentation and OpenAPI spec with current behavior for project management, authentication, and pagination.

Bug Fixes:

• Correct OpenAPI server base URL so generated clients hit the intended /api/v1 routes instead of double-prefixing /api.
• Clarify that project CRUD endpoints are dashboard/Clerk-only and return 401 for API-key usage, removing misleading API-key project examples.
• Update pagination docs to consistently describe the { data, pagination: { limit, next_cursor } } response shape without top-level has_more or total on conversation/message lists.

Enhancements:

• Simplify and unify pagination examples across static content and agents docs, including TypeScript samples and conventions.
• Document that projects API is dashboard-only, with /api/v1/projects/* as the sole path (no /v1/projects alias) and that org filtering is derived from the Clerk session rather than request parameters.

Documentation:

• Revise agents.md, static.ts, and api-reference.md to reflect accurate project management flows, API key usage, and pagination semantics, including updated field names in project list responses.

[sourcery-ai]

Sorry @duyetbot, you have reached your weekly rate limit of 500000 diff characters.

Please try again later or upgrade to continue using Sourcery

[coderabbitai]

Warning

Review limit reached

@duyetbot, you've reached your PR review limit, so we couldn't start this review.

Next review available in: 116 minutes

You've used all free OSS reviews for now. Wait for the free limit to reset to keep reviewing this public repository.

How can I continue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based reviews.

How do review limits work?

CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability.

For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling window.

Please refer docs for additional details.

Review details

⚙️ Run configuration

Configuration used: Organization UI

Review profile: ASSERTIVE

Plan: Pro Plus

Run ID: 4751b16d-e99e-432e-b2b9-b0051b8131bd

📥 Commits

Reviewing files that changed from the base of the PR and between 39c28e4 and 87bce31.

📒 Files selected for processing (5)

• docs/api-reference.md
• packages/api/src/content/agents.md
• packages/api/src/content/llms.txt
• packages/api/src/content/openapi.ts
• packages/api/src/content/static.ts

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[sourcery-ai]

Reviewer's Guide

This PR updates API documentation and the embedded OpenAPI spec to match the live behavior: fixing the server URL, standardizing pagination response shape, and clearly marking project CRUD as dashboard/Clerk-only instead of API-key accessible.

Sequence diagram for updated pagination response shape

sequenceDiagram
  actor Developer
  participant API

  Developer->>API: GET /api/v1/conversations?limit=50
  API-->>Developer: { data, pagination: { limit, next_cursor } }
  alt [pagination.next_cursor not null]
    Developer->>API: GET /api/v1/conversations?limit=50&cursor=pagination.next_cursor
    API-->>Developer: { data, pagination: { limit, next_cursor } }
  else [pagination.next_cursor is null]
    Developer-->>Developer: Stop pagination
  end

Loading

File-Level Changes

Change	Details	Files
Standardize pagination docs to the live { data, pagination: { limit, next_cursor } } shape and update usage examples accordingly.	Replace dual-shape pagination description with a single cursor-based response shape using a pagination object. Update TypeScript examples to destructure { data, pagination } instead of { data, has_more, next_cursor }. Clarify that next_cursor is null on the final page and must be passed as ?cursor= (or ?after= for message lists). Note that some state/claim queries may include total inside pagination instead of a separate top-level field.	packages/api/src/content/static.ts packages/api/src/content/agents.md docs/api-reference.md
Correct project management documentation to show projects as dashboard/Clerk-only, remove API-key-based project CRUD examples, and clarify pathing.	Replace lists of API-key-accessible /api/v1/projects CRUD endpoints with prose stating those routes are dashboard/Clerk-only and return 401 for Bearer keys. Clarify that /v1/projects is not mounted and that project endpoints live at /api/v1/projects/* only. Remove example code that uses an API key to POST /api/v1/projects and instead emphasize creating projects and initial keys via the dashboard. Adjust Projects API section to indicate Clerk session authentication, remove pagination parameters on GET /api/v1/projects, and align response fields (e.g., id instead of project_id). Explain that API keys are minted via key-scoped /api/v1/keys after projects exist, not via project CRUD via API keys.	packages/api/src/content/static.ts packages/api/src/content/agents.md docs/api-reference.md
Update OpenAPI spec server configuration to avoid double /api in generated client URLs.	Change the OpenAPI servers[0].url from https://agentstate.app/api to https://agentstate.app so documented paths like /api/v1/conversations resolve correctly. Ensure generated clients will call https://agentstate.app/api/v1/... instead of https://agentstate.app/api/api/v1/....	packages/api/src/content/openapi.ts
Tighten API key management docs and remove outdated project-key examples.	Retitle API Key Management section from keyless to key-scoped, clarifying that the project is taken from the authenticating key. Emphasize that a freshly generated key is returned once at creation and must be stored securely. Remove references to managing keys by fetching projects with API keys, in favor of key-scoped /api/v1/keys endpoints.	packages/api/src/content/static.ts packages/api/src/content/agents.md

Assessment against linked issues

Issue	Objective	Addressed	Explanation
#333	Update documentation so the Projects API section no longer refers to unmounted /v1/projects routes and correctly describes the actual mounted /api/v1/projects paths and their usage.	✅
#411	Set the OpenAPI server URL to https://agentstate.app (so /api/v1/* paths are not doubled to /api/api/v1/*).	✅
#411	Update documentation (agents.md, llms.txt, docs/api-reference.md, static.ts) to stop teaching API-key project CRUD, and clearly document that project CRUD is Clerk/dashboard-only, that API-key calls to /api/v1/projects return 401, and that /v1/projects is not mounted.	✅
#411	Make pagination documentation consistent with the live API by using the shape { data, pagination: { limit, next_cursor } } everywhere, removing references to has_more and top-level total while still noting that some state/claim queries include total inside pagination, and regenerate static.ts accordingly.	✅

---

Tips and commands

Interacting with Sourcery

• Trigger a new review: Comment @sourcery-ai review on the pull request.
• Continue discussions: Reply directly to Sourcery's review comments.
• Generate a GitHub issue from a review comment: Ask Sourcery to create an
  issue from a review comment by replying to it. You can also reply to a
  review comment with @sourcery-ai issue to create an issue from it.
• Generate a pull request title: Write @sourcery-ai anywhere in the pull
  request title to generate a title at any time. You can also comment
  @sourcery-ai title on the pull request to (re-)generate the title at any time.
• Generate a pull request summary: Write @sourcery-ai summary anywhere in
  the pull request body to generate a PR summary at any time exactly where you
  want it. You can also comment @sourcery-ai summary on the pull request to
  (re-)generate the summary at any time.
• Generate reviewer's guide: Comment @sourcery-ai guide on the pull
  request to (re-)generate the reviewer's guide at any time.
• Resolve all Sourcery comments: Comment @sourcery-ai resolve on the
  pull request to resolve all Sourcery comments. Useful if you've already
  addressed all the comments and don't want to see them anymore.
• Dismiss all Sourcery reviews: Comment @sourcery-ai dismiss on the pull
  request to dismiss all existing Sourcery reviews. Especially useful if you
  want to start fresh with a new review - don't forget to comment
  @sourcery-ai review to trigger a new review!

Customizing Your Experience

Access your dashboard to:

• Enable or disable review features such as the Sourcery-generated pull request
  summary, the reviewer's guide, and others.
• Change the review language.
• Add, remove or edit custom review instructions.
• Adjust other review settings.

Getting Help

• Contact our support team for questions or feedback.
• Visit our documentation for detailed guides and information.
• Keep in touch with the Sourcery team by following us on X/Twitter, LinkedIn or GitHub.