API reference
Find the request, fields and response examples for each OriginChainDB API operation.
Use the API to store records, run queries and manage your database. Each endpoint page shows its purpose, required inputs and copyable request and response examples.
- Choose the taskFind a record, query, search or management operation.
- Read its contractCheck the method, address, required fields and credential.
- Handle its resultUse the documented response and error guidance.
Set up your connection
Make your first requests
Connection setup
For application SQL, use POST $OC_URL/sql with Authorization: Bearer $OC_TOKEN. Copy OC_URL exactly from Connect; do not add or remove tenant segments.
Access-token support depends on the deployment's reported Connect capability. Supported dedicated, non-raft, non-sharded configurations can use access tokens; other configurations still need the instance credential shown in Connect.
The endpoint reference also documents explicit paths such as /v1/tenants/{tenant}/sql. Those examples use OC_BASE_URL and OC_TENANT for that contract. They are not instructions to reconstruct your Connect URL. Control-plane endpoints have separate credentials and connection details.
Read an endpoint
An endpoint is one operation at a specific URL. The method tells you how to call it; the input tables tell you what to supply.
| Input location | What you supply |
|---|---|
| Path | Replace placeholders such as {schema} with the target resource's identifier. |
| Query | Add options after ?, such as a result limit or cursor. |
| Headers | Send the credential and any content type or version condition. |
| Body | Send the JSON, text or file described by that operation. |
Only fields marked Required must always be present. Optional fields can still become necessary for a particular mode; check the rules below the table.
- Check its method and path.
- Complete the prerequisites and fill in required inputs.
- Choose cURL, HTTP, JavaScript or Python. Replace the example values.
- Inspect the HTTP status and response body.
Examples use sample data and do not run from this website. Use a development database for the quickstart writes.
Check available features
Read the capabilities endpoint before depending on an operation. Support can vary by engine build, configuration and permissions.
Browse the reference
Schemas
Define a table before writing its records.
Register a schema · List schemas · Start a schema migration
Records
Write, retrieve or delete ordinary table rows by primary key.
Write a row · Write a batch · Retrieve a row
SQL and transactions
Run a SQL statement or keep related operations inside a transaction.
Execute SQL · Begin a transaction · Create a materialized view
Graph
Follow relationships, find paths or analyze connected data.
List neighbors · Find a path · Execute Cypher
Vector
Store embeddings and search by similarity. Vector-index records have their own namespace-based endpoints.
Store a vector · Find nearest vectors · Insert vector-index records
Full-text
Index words, search documents and work with text results.
Index a document · Search a text field · Aggregate results
Users and permissions
Create roles and users, assign grants and control which rows can be read.
Create a role · Set a grant · Set a row policy
Import and sync
Copy data from files or a supported source into your database.
Upload a file · PostgreSQL sync · MySQL sync · Object-storage import
Jobs and maintenance
Check background work and inspect database activity.
Check a background job · Read query metrics · Read usage and limits
Audit
Read, verify or export the tenant's audit history.
Read audit entries · Verify the log · Export the log
Vector index management
Manage vector indexes and their namespaces separately from SQL table schemas.
Create an index · Create a namespace · Read index counts
Control plane
Manage project vector indexes, embedding models and embedding credits with the control-plane credential.
List projects · List embedding models · Create embeddings
Retry carefully
A failed connection does not prove a write failed. Check the database state and the endpoint's retry behavior before sending it again. An idempotency key only helps where that operation supports it.
Response errors
Use the error guide to interpret status codes, and review request limits when handling throttling. Existing limits still apply.
Elasticsearch compatibility
For the compatible adapter, use the Elasticsearch guide and check its supported operations before moving an integration.
OpenAPI specifications
Use these files for complete schemas and generated clients. Use the sidebar to open an individual endpoint.