Introduction

Overview

The Parseo public API is a versioned REST API. All endpoints live under /external/v1/. Requests are authenticated with bearer API keys scoped to your team.

Base URL

https://app.parseo.app/external/v1

Versioning

The API follows a semver-compatible stability contract:

Backwards-compatible changes (no version bump required):

• Adding new optional fields to responses
• Adding new endpoints
• Loosening request validation
• Performance improvements and internal refactors
• Fixing error messages (but not error codes)

Breaking changes (require a new major version, e.g. /external/v2/):

• Removing any field from a response
• Removing or renaming a request field
• Changing the semantics of an existing field
• Changing error codes

Content Types

All request bodies use application/json unless the endpoint accepts file uploads (multipart/form-data).

All successful responses return application/json; charset=utf-8.

All error responses return application/problem+json; charset=utf-8 (RFC 7807).

Response Format

Successful responses return the resource directly at the top level — no data wrapper.

Error responses follow the RFC 7807 Problem Details format:

{
  "type": "https://docs.parseo.app/errors/error-registry",
  "title": "Invoice not found",
  "status": 404,
  "code": "invoice.not_found",
  "detail": "No invoice with that ID is visible to this API key.",
  "requestId": "req_8f2c3a4b5d6e7f8a"
}

Validation errors include an errors[] array:

{
  "type": "https://docs.parseo.app/errors/error-registry",
  "title": "Invalid request body",
  "status": 400,
  "code": "validation.invalid_body",
  "detail": "One or more fields failed validation",
  "errors": [
    {
      "field": "sellerContactId",
      "code": "validation.invalid_public_id",
      "message": "Expected a con_… public ID, got \"foo\""
    }
  ],
  "requestId": "req_8f2c3a4b5d6e7f8a"
}

See Error Registry for the full list of error codes.