Introduction

The Replo API lets you work with your Replo workspaces and projects programmatically from your own code, automations, or tools like n8n.

Base URL

All public API endpoints are served from:

https://api.replo.app/v1

Authentication

Create a public API key from your Replo Settings, then send it as a bearer token:

curl "https://api.replo.app/v1/products?projectId=$REPLO_PROJECT_ID" \
  -H "Authorization: Bearer $REPLO_PUBLIC_API_KEY" \
  -H "Replo-Api-Version: $REPLO_API_VERSION"

Each public API key uses the current permissions of the person who created it, limited by the key’s scopes. If either check fails, Replo returns a 404. The same status is used when a resource does not exist, so API responses do not confirm private resource IDs. If a known resource returns a 404, check the key’s scopes and its creator’s current project access.

API version

Every request must include the Replo-Api-Version header. See API versioning for the current supported version and upgrade guidance.

Save working documents to Files

Use Files for research and working documents; Assets is a separate media library. Grant your API key files.read to list or read files and files.write to create, rename, or move them. Copying an Asset also requires assets.read. Existing keys do not gain new scopes automatically. Use the project UUID returned by GET /v1/projects. Supply projectId when listing or creating files. Requests for an existing fileId resolve the project from that file. File ownership and sharing permissions still apply.

curl "https://api.replo.app/v1/files" \
  -H "Authorization: Bearer $REPLO_PUBLIC_API_KEY" \
  -H "Replo-Api-Version: $REPLO_API_VERSION" \
  -H "Content-Type: application/json" \
  --data "{\"projectId\":\"$REPLO_PROJECT_ID\",\"kind\":\"file\",\"name\":\"research.md\",\"source\":{\"type\":\"text\",\"text\":\"# Research\"}}"

Omitting parentId saves to My Files. Files accept text, base64 data, or an existing Asset as their source, up to 10 MiB. A duplicate name returns 409 conflict without overwriting. Read contents with GET /v1/files/{fileId}/content; the response contains complete text or a download URL valid for 15 minutes.

Error handling

All errors return a consistent JSON envelope with a code, a message, and a doc_url linking to that code’s documentation:

{
  "error": {
    "code": "not_found",
    "message": "The requested resource was not found.",
    "doc_url": "https://beta.docs.replo.app/api-reference/errors#not_found"
  }
}

See Errors for every code and how to recover from it.

Async operations and polling

Some operations, like agent sessions, run asynchronously. They return immediately with a resource ID, and you poll for status updates. Recommended polling pattern:

Call the create endpoint (e.g., POST /agent/sessions)
Receive 202 Accepted with a session ID
Poll the status endpoint every 5-10 seconds (e.g., GET /agent/sessions/{id})
If the response includes pendingInteractions, the session is blocked waiting on you: resolve each one with POST /agent/sessions/{id}/interactions/{interactionId}/resolve, then keep polling
Continue until status is completed or failed

Handling cold starts: New sessions may return 404 for 1-2 seconds during sandbox initialization. Use exponential backoff, with apiVersion set to the current version from API versioning:

async function pollWithBackoff(sessionId, maxAttempts = 10) {
  let delay = 1000;
  for (let i = 0; i < maxAttempts; i++) {
    const response = await fetch(`https://api.replo.app/v1/agent/sessions/${sessionId}`, {
      headers: {
        "Authorization": `Bearer ${apiKey}`,
        "Replo-Api-Version": apiVersion
      }
    });
    if (response.status === 404 && i < 3) {
      await new Promise(r => setTimeout(r, delay));
      delay *= 2;
      continue;
    }
    return response.json();
  }
}

Idempotency

Some operations are idempotent: calling them multiple times with the same input produces the same result.

Operation	Idempotent?	Notes
`GET` (all)	Yes	Safe to retry
`POST /agent/sessions`	No	Each call creates a new session
`POST /agent/sessions/{id}/messages`	No	Each call starts a new turn
`POST /agent/sessions/{id}/abort`	Yes	Aborting twice is a no-op
`POST /products`	No	Each call creates a new product
`PATCH /products/{id}`	Yes	Same update can be retried
`DELETE` (all)	Yes	Safe to retry; a repeat delete returns 404 `not_found`

When retrying non-idempotent operations after a network failure, check whether the original request succeeded before retrying to avoid duplicates.

MCP

To work with Replo through Claude or ChatGPT instead of making HTTP requests, use Replo’s MCP connection.

Overview

Endpoints

Changelog

Introduction

Base URL

Authentication

API version

Save working documents to Files

Error handling

Async operations and polling

Idempotency

MCP

​Base URL

​Authentication

​API version

​Save working documents to Files

​Error handling

​Async operations and polling

​Idempotency

​MCP

Base URL

Authentication

API version

Save working documents to Files

Error handling

Async operations and polling

Idempotency

MCP