Queries
Last updated
Last updated
Verida offers a suite of Query APIs that enable you to store, query, and manage user data across decentralized databases and datastores, as well as perform advanced searches. This page covers the Databases and Datastores sections of the Verida User API Reference.
For full technical details, consult the .
Datastores
Get a Record by ID (api:ds-get-by-id
)
Create a Record (api:ds-create
)
Update a Record (api:ds-update
)
Query a Datastore (api:ds-query
)
Count records (api:ds-query
)
Watch a Datastore (api:ds-query
)
Delete a Record (api:ds-delete
)
Databases
Get a Record by ID (api:db-get-by-id
)
Create a Record (api:db-create
)
Update a Record (api:db-update
)
Query a Database (api:db-query
)
Count records (api:db-query
)
Datastores are schema-based collections of structured data. Endpoints for datastores operate similarly to databases but typically refer to a base64-encoded schema URL or a well-known shortcut. Each datastore endpoint requires the relevant API scope (e.g., api:ds-get-by-id
) and uses 1 credit per request unless otherwise noted.
HTTP Method & Endpoint: GET /ds/{dsUrlEncoded}/{id}
Summary: Retrieve a specific record by its id
from a datastore.
Credit Usage: 1 credit
Scope: api:ds-get-by-id
Example:
HTTP Method & Endpoint: POST /ds/{dsUrlEncoded}
Summary: Insert a new record into the specified datastore.
Credit Usage: 1 credit
Scope: api:ds-create
Example:
HTTP Method & Endpoint: PUT /ds/{dsUrlEncoded}/{id}
Summary: Update an existing datastore record identified by id
.
Credit Usage: 1 credit
Scope: api:ds-update
Example:
HTTP Method & Endpoint: POST /ds/query/{dsUrlEncoded}
Summary: Run queries (similar to databases) from a datastore.
Credit Usage: 1 credit
Scope: api:ds-query
Example (Query):
HTTP Method & Endpoint: POST /ds/count/{dsUrlEncoded}
Summary: Count the number of results in a datastore that match a query
Credit Usage: 0 credits
Scope: api:ds-query
Example (Query):
HTTP Method & Endpoint: GET /ds/watch/{dsUrlEncoded}
Summary: Subscribe to real-time updates from a datastore. This is not a typical HTTP request, it uses EventSource to stream the database changes.
Credit Usage: 1 credit
Scope: api:ds-query
HTTP Method & Endpoint: DELETE /ds/{dsUrlEncoded}/{id}
Summary: Remove a record permanently from a datastore.
Credit Usage: 1 credit
Scope: api:ds-delete
Example:
Database endpoints allow you to work with traditional, table-like data. Each endpoint requires an auth_token
with the relevant API scope (e.g., api:db-get-by-id
) and consumes 1 credit per request unless otherwise noted.
HTTP Method & Endpoint: GET /db/{dbName}/{id}
Summary: Fetch a single record from a specific database using its unique id
.
Credit Usage: 1 credit
Scope: api:db-get-by-id
Example:
HTTP Method & Endpoint: POST /db/{dbName}
Summary: Insert a new record into the specified database.
Credit Usage: 1 credit
Scope: api:db-create
Example:
HTTP Method & Endpoint: PUT /db/{dbName}/{id}
Summary: Modify an existing record identified by id
in a specific database.
Credit Usage: 1 credit
Scope: api:db-update
Example:
HTTP Method & Endpoint: POST /db/query/{dbName}
Summary: Run queries to filter and retrieve multiple records from the specified database.
Credit Usage: 1 credit
Scope: api:db-query
Example:
HTTP Method & Endpoint: POST /db/count/{dbName}
Summary: Count the number of results in a database that match a query
Credit Usage: 0 credits
Scope: api:db-query
Example:
Secure Your Requests: Always include the Authorization: Bearer YOUR_AUTH_TOKEN
header and ensure your application only requests the necessary scopes.
Understand Credit Costs: Each API call draws from your available credits. Optimize your queries and reduce unnecessary calls.
Use the Right Endpoint: Databases vs. Datastores have subtle differences. Identify which storage mechanism and endpoint best suit your application.
Leverage Real-Time Updates: Where possible, use datastore watching (GET /ds/watch
) to keep application data in sync without continuous polling.
Respect Scope Requirements: For instance, if you need api:ds-delete
, your user must grant a scope that allows delete access (e.g., ds:rwd:file
).
Full Documentation:
Full Documentation:
Full Documentation:
Full Documentation:
Full Documentation:
Full Documentation:
Full Documentation:
Full Documentation:
Full Documentation: