Developer Documentation

Public API Reference

Introduction

The Recite Public API allows you to programmatically scan receipts, manage transactions, and export financial data. Our API is designed for ease of use and follows RESTful principles, making it compatible with AI agents, automation platforms (like Zapier or Make), and custom web/mobile applications.

Base URL:https://recite.rivra.dev/apiV1/api/v1

Authentication

All requests require a Bearer token in the Authorization header. You can create and manage your API keys in the dashboard.

Authorization: Bearer re_live_YOUR_API_KEY

Security: Never expose your API keys in client-side code, public repositories, or logs. If a key is compromised, rotate it immediately from the settings page.

Response Format

All API responses use a standard envelope. You can choose the format (JSON, CSV, or Text) via the ?format= query parameter or the Accept header.

{
  "success": true,
  "data": { ... },
  "meta": {
    "request_id": "550e8400-e29b-41d4-a716-446655440000",
    "api_version": "v1",
    "processing_time_ms": 1234
  }
}

Rate Limits

We enforce rate limits to ensure stability. Limits are applied per API key.

Window	Limit	Retry-After
Per minute	30 requests	60s
Per hour	500 requests	3600s
Per day	5,000 requests	Contact Support for more

Scopes & Permissions

Each API key can be restricted to specific scopes. If an endpoint requires a scope your key lacks, you'll receive a 403 Forbidden error.

Scope	Description
scan:create	Create new scans (/scan, batch)
scan:read	Read scan results
transactions:create	Create manual transactions
transactions:read	List and read transactions
transactions:update	Update existing transactions
batch:create	Submit batch scan jobs
projects:read	List project IDs

Error Codes

We use standard HTTP status codes along with specific error codes in the response body.

Status	Code	Meaning
400	INVALID_REQUEST	Malformed parameters or missing fields
401	INVALID_API_KEY	Missing or invalid Bearer token
403	INSUFFICIENT_SCOPE	Key lacks required scope
404	NOT_FOUND	Resource does not exist
429	RATE_LIMITED	Too many requests in a short window
429	QUOTA_EXCEEDED	Monthly scan limit reached

Scanning

Extract structured data from receipts using vision AI. We support image URLs, base64 data, and raw text.

Transactions

Import

Bulk-create transactions from a JSON array or a CSV file. No image processing occurs — you supply the field values directly.

Batch Scanning

Process multiple receipts asynchronously. Best for high-volume uploads.

Projects

Export

Webhooks

The API can notify your system when long-running tasks complete. Currently, webhooks are supported for Batch Scanning.

Batch Completion

When a batch job finishes, we send a POST request to your webhook_url.

{
  "event": "batch.completed",
  "job_id": "batch-uuid",
  "status": "completed",
  "summary": { "total": 5, "successful": 4, "failed": 1 },
  "timestamp": "2025-01-15T10:30:00Z"
}

Security: Always verify the X-Recite-Signature header using your webhook_secret to ensure the request came from Recite.

Usage Metrics

Try It Now

Ready to test? Use our interactive playground to send real requests to the Recite API.

Interactive Playground

Test the API directly from your browser. Your API key is sent directly to the API and never stored on our servers.

API Key

Image URL