API quickstart
Create a sample table, write three rows and query them through the explicit database HTTP API.
Create a small table, write three rows and query them. These examples use the explicit tenant-path API contract: complete the explicit endpoint setup first.
- Define demo.peopleSet its columns, primary key and follows relation.
- Add three peopleWrite records with IDs, scores and links.
- Read matching rowsRun SQL with a bound score parameter.
Start with steps 1–3. Choose one request-language tab at each step; the tabs are alternative ways to send the same request. Then try graph, text or vector queries using the optional examples below.
These requests create synthetic data; run them in a test database you control.
1. Create a schema
Register demo.people: id identifies a person, score is a number and follows_id points to another person. The follows relation gives graph queries a name for that connection. This step defines the shape; it does not add people yet.
Expected response: 200 — created. 409 indicates table already exists.
curl --include --request POST "${OC_BASE_URL}/v1/tenants/${OC_TENANT}/schemas" \
--header "Authorization: Bearer ${OC_TOKEN}" \
--header "Content-Type: text/plain; charset=utf-8" \
--data-binary 'namespace = "demo"
table = "people"
primary_key = ["id"]
[[columns]]
name = "id"
ty = "str"
required = true
[[columns]]
name = "follows_id"
ty = "str"
[[columns]]
name = "score"
ty = "i64"
[[relations]]
name = "follows"
from_col = "follows_id"
bidirectional = true
[relations.target]
namespace = "demo"
table = "people"
pk = "id"
'View success & error examples
{
"id": "demo.people",
"tenant": "your-tenant"
}{
"error": "Invalid request: check the fields and values."
}Correct the request before retrying.
{
"error": "Missing or invalid bearer credential."
}Check the credential and Authorization header.
{
"error": "This operation requires available credits or feature access."
}Check feature access or available credits.
{
"error": "The credential does not have access to this operation."
}Check tenant access, roles and permissions.
{
"error": "Schema already exists",
"class": "schema_already_exists"
}Illustrates the schema_already_exists class; choose a new table ID.
Resolve the conflict before retrying.
{
"error": "The request body exceeds the allowed size."
}Split or reduce the request body.
{
"error": "Too many requests. Retry after backing off."
}Honor Retry-After when present; back off.
{
"error": "The server could not complete the request."
}Check the outcome before retrying a write.
{
"error": "This operation is not supported by this deployment."
}Check deployment support for this operation.
{
"error": "An upstream service returned an invalid response."
}Check service availability and the write outcome.
{
"error": "The service is temporarily unavailable."
}Honor Retry-After when present; check write outcomes.
2. Add three connected rows
Use the schema from step 1. The JSON array writes three rows together: each has its own id, and follows_id refers to another row. For this JSON-array endpoint, all three rows are accepted together or the write fails; this does not describe every batch format.
Expected response: 200 — inserted: 3. 400 indicates invalid row or field.
curl --include --request POST "${OC_BASE_URL}/v1/tenants/${OC_TENANT}/rows/demo.people/_batch" \
--header "Authorization: Bearer ${OC_TOKEN}" \
--header "Content-Type: application/json" \
--data-binary '[
{
"id": "u1",
"follows_id": "u2",
"score": 10
},
{
"id": "u2",
"follows_id": "u3",
"score": 20
},
{
"id": "u3",
"follows_id": "u1",
"score": 30
}
]'View success & error examples
{
"inserted": 3
}The displayed JSON array writes all three rows atomically.
{
"inserted": 2,
"error": "Example streaming failure after committed chunks."
}207 applies to a separate NDJSON streaming request, not the displayed atomic JSON array; two rows stay committed in this illustrative failure.
{
"error": "Invalid request: check the fields and values."
}Correct the request before retrying.
{
"error": "Missing or invalid bearer credential."
}Check the credential and Authorization header.
{
"error": "This operation requires available credits or feature access."
}Check feature access or available credits.
{
"error": "The credential does not have access to this operation."
}Check tenant access, roles and permissions.
{
"error": "The requested resource was not found."
}Check the resource ID and API route.
{
"error": "The request conflicts with the current resource state."
}Resolve the conflict before retrying.
{
"error": "The request body exceeds the allowed size."
}Split or reduce the request body.
{
"error": "The request Content-Type is not supported."
}Send the required Content-Type.
{
"error": "The supplied values cannot be processed."
}Correct the values or unsupported combination.
{
"error": "Too many requests. Retry after backing off."
}Honor Retry-After when present; back off.
{
"error": "The server could not complete the request."
}Check the outcome before retrying a write.
{
"error": "This operation is not supported by this deployment."
}Check deployment support for this operation.
{
"error": "The service is temporarily unavailable."
}Honor Retry-After when present; check write outcomes.
3. Query with SQL
Query the rows from step 2. $1 takes the value 10 from params, so the statement returns id and score for people scoring at least 10. Read columns with rows to identify the returned values; changing the parameter changes the filter without rewriting SQL.
Expected response: 200 — query result. 400 indicates invalid SQL or schema.
curl --include --request POST "${OC_BASE_URL}/v1/tenants/${OC_TENANT}/sql" \
--header "Authorization: Bearer ${OC_TOKEN}" \
--header "Content-Type: application/json" \
--data-binary '{
"sql": "SELECT id, score FROM demo.people WHERE score >= $1 ORDER BY id LIMIT 10",
"params": [
10
]
}'View success & error examples
{
"kind": "select",
"columns": [
"id",
"score"
],
"rows": [
{
"id": "u1",
"score": 10
},
{
"id": "u2",
"score": 20
},
{
"id": "u3",
"score": 30
}
]
}{
"kind": "droptable_accepted",
"schema": "demo.people",
"status": "accepted"
}202 belongs to a DROP TABLE statement, not the SELECT request shown here; inspect the actual returned reclamation/status fields.
{
"error": "Invalid request: check the fields and values."
}Correct the request before retrying.
{
"error": "Missing or invalid bearer credential."
}Check the credential and Authorization header.
{
"error": "This operation requires available credits or feature access."
}Check feature access or available credits.
{
"error": "The credential does not have access to this operation."
}Check tenant access, roles and permissions.
{
"error": "The requested resource was not found."
}Check the resource ID and API route.
{
"error": "The request exceeded its time limit."
}Reduce query work or adjust the timeout.
{
"error": "The request conflicts with the current resource state."
}Resolve the conflict before retrying.
{
"error": "The request body exceeds the allowed size."
}Split or reduce the request body.
{
"error": "The request Content-Type is not supported."
}Send the required Content-Type.
{
"error": "The supplied values cannot be processed."
}Correct the values or unsupported combination.
{
"error": "Too many requests. Retry after backing off."
}Honor Retry-After when present; back off.
{
"error": "The client cancelled the request."
}The client cancelled the request.
{
"error": "The server could not complete the request."
}Check the outcome before retrying a write.
{
"error": "This operation is not supported by this deployment."
}Check deployment support for this operation.
{
"error": "An upstream service returned an invalid response."
}Check service availability and the write outcome.
{
"error": "The service is temporarily unavailable."
}Honor Retry-After when present; check write outcomes.
Optional: follow graph relationships
4. Follow relationships
Use the schema and rows from steps 1–2. Start at u1, follow the follows relation and visit nodes up to two links away. The result describes reachable nodes; it is not a ranked text or similarity search.
Expected response: 200 — reachable nodes. 400 indicates invalid relation.
curl --include --request GET "${OC_BASE_URL}/v1/tenants/${OC_TENANT}/graph/demo.people/bfs?rel=follows&pk=u1&max_depth=2" \
--header "Authorization: Bearer ${OC_TOKEN}"View success & error examples
[
{
"depth": 1,
"pk": "u2"
},
{
"depth": 2,
"pk": "u3"
}
]Illustrative traversal entries; the versioned canary proves u3 at depth 2, not this full response or its ordering.
{
"error": "Invalid request: check the fields and values."
}Correct the request before retrying.
{
"error": "Missing or invalid bearer credential."
}Check the credential and Authorization header.
{
"error": "This operation requires available credits or feature access."
}Check feature access or available credits.
{
"error": "The credential does not have access to this operation."
}Check tenant access, roles and permissions.
{
"error": "The requested resource was not found."
}Check the resource ID and API route.
{
"error": "The request exceeded its time limit."
}Reduce query work or adjust the timeout.
{
"error": "Too many requests. Retry after backing off."
}Honor Retry-After when present; back off.
{
"error": "The client cancelled the request."
}The client cancelled the request.
{
"error": "The server could not complete the request."
}Check the outcome before retrying a write.
{
"error": "The service is temporarily unavailable."
}Honor Retry-After when present; check write outcomes.
Optional: index and search text
5. Index a document
Add the words in a short description to the demo_docs.body text index, using document ID p1. This is separate from the people table above. Indexing makes words searchable; storing source text for display is a separate operation.
Expected response: 201 — indexed. 400 indicates invalid input.
curl --include --request POST "${OC_BASE_URL}/v1/tenants/${OC_TENANT}/fts/demo_docs/body" \
--header "Authorization: Bearer ${OC_TOKEN}" \
--header "Content-Type: application/json" \
--data-binary '{
"doc_id": "p1",
"text": "Trail mug with insulated steel"
}'View success & error examples
HTTP/1.1 201
No response body specified by the contract.{
"error": "Invalid request: check the fields and values."
}Correct the request before retrying.
{
"error": "Missing or invalid bearer credential."
}Check the credential and Authorization header.
{
"error": "This operation requires available credits or feature access."
}Check feature access or available credits.
{
"error": "The credential does not have access to this operation."
}Check tenant access, roles and permissions.
{
"error": "The request conflicts with the current resource state."
}Resolve the conflict before retrying.
{
"error": "The request body exceeds the allowed size."
}Split or reduce the request body.
{
"error": "The request Content-Type is not supported."
}Send the required Content-Type.
{
"error": "The supplied values cannot be processed."
}Correct the values or unsupported combination.
{
"error": "Too many requests. Retry after backing off."
}Honor Retry-After when present; back off.
{
"error": "The server could not complete the request."
}Check the outcome before retrying a write.
{
"error": "An upstream service returned an invalid response."
}Check service availability and the write outcome.
{
"error": "The service is temporarily unavailable."
}Honor Retry-After when present; check write outcomes.
6. Search by keyword
Search the text indexed in step 5 for trail. Each hit identifies a matching document and its ranking score; use doc_id to relate the hit to your source. k=5 caps the returned hits rather than guaranteeing five matches.
Expected response: 200 — ranked matches. 400 indicates invalid search parameters.
curl --include --request GET "${OC_BASE_URL}/v1/tenants/${OC_TENANT}/fts/demo_docs/body?q=trail&mode=bm25&k=5" \
--header "Authorization: Bearer ${OC_TOKEN}"View success & error examples
[
{
"doc_id": "p1",
"score": 0.2877
}
]Illustrative BM25 score; values depend on corpus statistics.
{
"error": "Invalid request: check the fields and values."
}Correct the request before retrying.
{
"error": "Missing or invalid bearer credential."
}Check the credential and Authorization header.
{
"error": "This operation requires available credits or feature access."
}Check feature access or available credits.
{
"error": "The credential does not have access to this operation."
}Check tenant access, roles and permissions.
{
"error": "The requested resource was not found."
}Check the resource ID and API route.
{
"error": "The request exceeded its time limit."
}Reduce query work or adjust the timeout.
{
"error": "The request body exceeds the allowed size."
}Split or reduce the request body.
{
"error": "Too many requests. Retry after backing off."
}Honor Retry-After when present; back off.
{
"error": "The client cancelled the request."
}The client cancelled the request.
{
"error": "The server could not complete the request."
}Check the outcome before retrying a write.
{
"error": "This operation is not supported by this deployment."
}Check deployment support for this operation.
{
"error": "The service is temporarily unavailable."
}Honor Retry-After when present; check write outcomes.
Optional: store and search vectors
7. Store an embedding
Store a three-number embedding under ID v1 in demo_vectors. These hand-written numbers demonstrate the request shape; they do not represent real text meaning. For an application, generate stored and query embeddings with the same model and dimension.
Expected response: 201 — stored. 400 indicates invalid vector dimensions.
curl --include --request POST "${OC_BASE_URL}/v1/tenants/${OC_TENANT}/vector/demo_vectors/put" \
--header "Authorization: Bearer ${OC_TOKEN}" \
--header "Content-Type: application/json" \
--data-binary '{
"id": "v1",
"embedding": [
0.1,
0.2,
0.3
],
"dim": 3,
"metric": "cosine",
"metadata": {
"category": "outdoor"
}
}'View success & error examples
HTTP/1.1 201
No response body specified by the contract.{
"error": "Invalid request: check the fields and values."
}Correct the request before retrying.
{
"error": "Missing or invalid bearer credential."
}Check the credential and Authorization header.
{
"error": "This operation requires available credits or feature access."
}Check feature access or available credits.
{
"error": "The credential does not have access to this operation."
}Check tenant access, roles and permissions.
{
"error": "The request conflicts with the current resource state."
}Resolve the conflict before retrying.
{
"error": "The request body exceeds the allowed size."
}Split or reduce the request body.
{
"error": "The request Content-Type is not supported."
}Send the required Content-Type.
{
"error": "The supplied values cannot be processed."
}Correct the values or unsupported combination.
{
"error": "Too many requests. Retry after backing off."
}Honor Retry-After when present; back off.
{
"error": "The server could not complete the request."
}Check the outcome before retrying a write.
{
"error": "The service is temporarily unavailable."
}Honor Retry-After when present; check write outcomes.
8. Search by similarity
Search the vectors from step 7 with cosine similarity. The query uses the same three dimensions as the stored vector. Read each returned ID and score; a real semantic search needs meaningful embeddings, not the illustrative numbers used here.
Expected response: 200 — nearest vectors. 400 indicates invalid query vector.
curl --include --request POST "${OC_BASE_URL}/v1/tenants/${OC_TENANT}/vector/demo_vectors/topk" \
--header "Authorization: Bearer ${OC_TOKEN}" \
--header "Content-Type: application/json" \
--data-binary '{
"query": [
0.1,
0.2,
0.3
],
"dim": 3,
"metric": "cosine",
"k": 5
}'View success & error examples
[
{
"id": "v1",
"score": 1
}
]Illustrates a collection with only the quickstart vector v1; scores depend on your data.
{
"error": "Invalid request: check the fields and values."
}Correct the request before retrying.
{
"error": "Missing or invalid bearer credential."
}Check the credential and Authorization header.
{
"error": "This operation requires available credits or feature access."
}Check feature access or available credits.
{
"error": "The credential does not have access to this operation."
}Check tenant access, roles and permissions.
{
"error": "The request exceeded its time limit."
}Reduce query work or adjust the timeout.
{
"error": "The request conflicts with the current resource state."
}Resolve the conflict before retrying.
{
"error": "The request body exceeds the allowed size."
}Split or reduce the request body.
{
"error": "The request Content-Type is not supported."
}Send the required Content-Type.
{
"error": "The supplied values cannot be processed."
}Correct the values or unsupported combination.
{
"error": "Too many requests. Retry after backing off."
}Honor Retry-After when present; back off.
{
"error": "The client cancelled the request."
}The client cancelled the request.
{
"error": "The server could not complete the request."
}Check the outcome before retrying a write.
{
"error": "This operation is not supported by this deployment."
}Check deployment support for this operation.
{
"error": "The service is temporarily unavailable."
}Honor Retry-After when present; check write outcomes.
9. Handle an error
On a bearer-protected deployment, a missing token should return 401.
Add a valid token, then retry.
# Negative example: authentication is intentionally omitted.
curl --include "$OC_BASE_URL/v1/tenants/$OC_TENANT/schemas"Responses illustrate contract shapes; runtime values and deployment support can differ. Existing versioned checks cover a subset of workflows.