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

Authentication is route-specific. Dashboard REST routes use the signed-in session; machine-facing routes document API-key support explicitly.

API Keys for Machine-Facing Routes

Hosted MCP and API-key-enabled project routes accept a key with access to the target project. Include it in the X-API-Key header:

curl -H "X-API-Key: $SNIPARA_API_KEY"   https://api.snipara.com/mcp/YOUR_PROJECT_SLUG

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

{

  "success": true,

  "data": [

    {

      "id": "proj_abc123",

      "slug": "my-documentation",

      "name": "My Documentation",

      "_count": { "documents": 42, "queries": 8 }

    }

  ]

}

Create Project

POST /api/projects

Request Body

{

  "name": "My New Project",

  "slug": "my-new-project",

  "description": "Current project context."

}

slug is required, must be unique in the workspace, and may contain lowercase letters, numbers, and hyphens. Successful creation returns HTTP 201 with the standard { "success": true, "data": ... } envelope.

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 Billing and Usage

GET /api/billing?teamId=:teamId

Response

{

  "success": true,

  "data": {

    "subscription": { "plan": "PRO", "effectivePlan": "PRO" },

    "usage": { "queries": 1250, "limit": 25000, "percentage": 5 },

    "plan": { "name": "Pro", "rateLimit": 120 },

    "billingPeriod": { "start": "...", "end": "..." }

  }

}

Manage Subscription

POST /api/billing/portal

Body: { "teamId": "team_abc123" }

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

Error Responses

Core dashboard REST routes using the shared error handler return this envelope:

{

  "error": {

    "code": "UNAUTHORIZED",

    "message": "Authentication required"

  }

}

Common Error Codes

Rate Limits

API rate limits vary by plan:

These are the web REST surface limits shown by the dashboard contract. Hosted MCP/Python client quotas are a separate surface and may use different monthly allowances; do not copy this table into an MCP client configuration without checking the active plan and caller.

Next Steps