Cloud API

Use the Cloud API to build integrations, retrieve conversation history, and search the sessions you sync to SpecStory Cloud. Start with REST for project and session operations, or use GraphQL to query across your data.

Send requests to https://cloud.specstory.com.

Include your API key as a Bearer token in the Authorization header. The authentication guide explains how to obtain a key and use it from your preferred language.

REST API

Use individual endpoints to work with projects and sessions:

• Projects: list projects, update their details, or delete a project.
• Sessions: list sessions in a project, retrieve a conversation, or get recent sessions across projects.
• Conditional requests: check a session before downloading its content.

Each endpoint includes its HTTP method, path, parameters, response fields, and request examples.

GraphQL API

Use GraphQL when you need full-text search, metadata filters, or selected fields from related projects and sessions. Send queries to POST /api/v1/graphql.

The query examples cover full-text search, project filters, and more advanced queries. You can also explore the schema in the GraphQL explorer.

ETags and conditional requests

Session responses include an ETag that identifies the content version. Send it in If-None-Match on a later request to avoid downloading unchanged content. A matching version returns 304 Not Modified. See Get Session and Check Session.

JSON and Markdown

Retrieve structured session data as JSON or the conversation itself as Markdown. The Get Session reference documents the available formats and response fields.

Session metadata

Use client details, git context, model information, and tags to understand and organize your history. The GraphQL overview explains how to select and filter the fields you need.

The Cloud API documents these limits per API key:

Read X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset from responses to track your current allowance. The reset value is a UTC Unix timestamp in seconds. See error handling for handling 429 responses and retrying requests.

1. Sign in to SpecStory Cloud and create an API key.
2. List your projects with an authenticated request:

curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://cloud.specstory.com/api/v1/projects

3. Use a project ID from the response to list its sessions.
4. Retrieve a session, or try the GraphQL examples to search your history.

Use an HTTP client or GraphQL library with these endpoints. The reference includes cURL, JavaScript, and Python examples; the authentication guide also includes Go.

Check the error reference for status codes and recovery steps. For API help, email support@specstory.com. Report documentation issues on GitHub.