API Reference

The Snipara REST API is the primary interface for apps, integrators, backends, and pipelines. Use it for product workflows that need stable auth, bulk upload, sync, health, analytics, and lifecycle operations.

Authentication

Snipara supports two authentication methods:

API Keys (Recommended)

Generate an API key from your Snipara settings with access to the target project. Include it in the X-API-Key header:

curl -H "X-API-Key: snp-xxx" https://api.snipara.com/...

Session Authentication

When making requests from the browser while logged in, session cookies are automatically included. This is used by the dashboard.

Base URL

https://www.snipara.com/api

API Endpoints

Projects API

List Projects

GET /api/projects

Returns a list of all projects you have access to.

Response

{

  "projects": [

    {

      "id": "proj_abc123",

      "name": "My Documentation",

      "documentCount": 42,

      "createdAt": "2024-01-15T10:30:00Z"

    }

  ]

}

Create Project

POST /api/projects

Request Body

{

  "name": "My New Project",

  "description": "Current project context.",

  "businessLifecycle": "ACTIVE_CLIENT"

}

Partner-backed project workflows can set businessLifecycle to ACTIVE_CLIENT, REFERENCE_ARCHIVE, or INTERNAL_BUSINESS. Direct Snipara dashboard projects stay focused on developer and repository context.

Partner Business Workspaces API

Approved partner backends can provision customer workspaces while keeping their own frontend and commercial UX. Snipara remains the backend source of truth for the real team, users, projects, context, and service-account MCP access.

Provision Workspace

POST /api/v1/partners/business-workspaces

Required Scope

business_workspaces:write

Request Body

{

  "external_workspace_id": "acme-prod",

  "external_customer_id": "cust_acme",

  "name": "Acme",

  "owner_email": "owner@acme.com",

  "plan": "TEAM",

  "seat_limit": 5

}

plan accepts TEAM or ENTERPRISE. workspaceIdin child routes accepts either Snipara's workspace ID or the partner's external_workspace_id.

Workspace Operations

Create Project-Scoped Service Account

POST /api/v1/partners/business-workspaces/:workspaceId/service-accounts

{

  "name": "CI",

  "project_access": [

    { "project_id": "project_1", "access_level": "EDITOR" }

  ]

}

The raw snp-bot- key is returned only once. Service account keys never imply global workspace access; every project must have an explicit VIEWER, EDITOR, or ADMIN grant.

Documents API

Upload Document

POST /api/projects/:projectId/documents

Request Body

{

  "path": "docs/getting-started.md",

  "content": "# Getting Started\n\nWelcome to..."

}

The path field is used as both the document identifier and display name. Uploading to an existing path will update that document.

List Documents

GET /api/projects/:projectId/documents

Delete Document

DELETE /api/projects/:projectId/documents/:documentId

Billing API

Get Usage

GET /api/billing/usage

Response

{

  "plan": "pro",

  "queriesUsed": 1250,

  "queriesLimit": 10000,

  "periodStart": "2024-01-01T00:00:00Z",

  "periodEnd": "2024-01-31T23:59:59Z"

}

Manage Subscription

POST /api/billing/portal

Returns a URL to the Stripe Customer Portal where users can manage their subscription, update payment methods, and view invoices.

Error Responses

All API errors follow a consistent format:

{

  "error": {

    "code": "UNAUTHORIZED",

    "message": "Invalid API key",

    "status": 401

  }

}

Common Error Codes

Rate Limits

API rate limits vary by plan:

Next Steps