Skip to content

Platform API

The platform API is the REST surface over your Autopoetic workspace: the same operations the web app performs, available to your code. It reads and writes your data — it never runs the agent (generation is the Responses API's job; see the API overview).

Base URL:  https://app.autopoetic.ai/api/v1
Auth:      Authorization: Bearer YOUR_API_KEY

API keys are created by a project admin and carry the project's admin role — see projects and teams.

What you can manage

  • Conversations — list, create, read, update settings, delete; fork, publish and unpublish (public links), revert to a message, and export the transcript as Markdown.
  • Messages — append, list, read, and soft-delete messages in a conversation, with cursor pagination.
  • The knowledge repository — search; create, read, update, and delete entries; create and delete relationships; record events; batch operations. See the knowledge repository.
  • Projects — create under a customer, read, rename, delete, and fork (with its knowledge).
  • Members and invitations — list members, remove members, create and cancel invitations; accept or decline user-scoped invitations.
  • API keys — create, list, and delete project API keys.
  • Workflows — templates, runs, and the decision engine. See the workflows section.

Path shapes vary by resource — conversations, messages, projects, and members are customer-scoped (/api/v1/customers/{customer_uuid}/projects/{project_uuid}/...) while knowledge and workflows are project-direct (/api/v1/projects/{project_uuid}/...). The schema page is the authoritative reference; don't guess a path shape.

Conventions

  • Roles: routes are tiered like the UI roles — reads generally need viewer+, writes editor+, project management admin+ (an API key acts as the project's admin).
  • Pagination: list endpoints use offset/limit (max page size 100) or opaque cursor tokens — message pages take a before cursor, event pages an after cursor. Cursors are encrypted tokens; pass them back verbatim.
  • Errors: JSON error envelopes with structured codes, including the usage-limit errors (pricing).

The endpoint reference

The full endpoint table — paths, methods, parameters, request and response schemas, and error codes for every route — lives on the live OpenAPI schema page, generated from the server itself:

https://app.autopoetic.ai/schema

This page deliberately does not duplicate that table. The schema always matches the deployed server, including your deployment's feature set. Raw spec for tooling: https://app.autopoetic.ai/schema/openapi.json.

Examples

List a project's conversations:

curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://app.autopoetic.ai/api/v1/customers/{customer_uuid}/projects/{project_uuid}/conversations?limit=25"

Search the knowledge repository by name (name=* lists everything):

curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://app.autopoetic.ai/api/v1/projects/{project_uuid}/knowledge/search?name=jones"

Append a user message — stored encrypted, metered against your plan, and no agent turn is generated (drive the agent's reply with the Responses API on the same conversation):

curl -X POST \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  "https://app.autopoetic.ai/api/v1/customers/{customer_uuid}/projects/{project_uuid}/conversations/{conversation_uuid}/messages" \
  -d '{"role": "user", "body": "Note to self: ask about the launch plan tomorrow."}'