Queries

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 Verida API Reference Documentation.

Table of Contents

1. 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)

2. 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

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.

1. Get a Record by ID

• 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:

  # dsUrlEncoded is typically the base64-encoded schema URL or a known shortcut
  curl -X GET "https://api.verida.ai/api/rest/v1/ds/aHR0cHM6Ly9....json/456" \
       -H "Authorization: Bearer YOUR_AUTH_TOKEN"

• Full Documentation: Datastore: Get Record by ID

---

2. Create a Record

• HTTP Method & Endpoint: POST /ds/{dsUrlEncoded}

• Summary: Insert a new record into the specified datastore.

• Credit Usage: 1 credit

• Scope: api:ds-create

• Example:

  curl -X POST "https://api.verida.ai/api/rest/v1/ds/aHR0cHM6Ly9.../" \
       -H "Authorization: Bearer YOUR_AUTH_TOKEN" \
       -H "Content-Type: application/json" \
       -d '{
         "key": "value",
         "createdAt": "2025-02-03T12:00:00Z"
       }'

• Full Documentation: Datastore: Create Record

---

3. Update a Record

• 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:

  curl -X PUT "https://api.verida.ai/api/rest/v1/ds/aHR0cHM6Ly9.../456" \
       -H "Authorization: Bearer YOUR_AUTH_TOKEN" \
       -H "Content-Type: application/json" \
       -d '{
         "updatedKey": "newValue"
       }'

• Full Documentation: Datastore: Update Record

---

4. Query a Datastore

• 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):

  curl -X POST "https://api.verida.ai/api/rest/v1/ds/query/aHR0cHM6Ly9..." \
       -H "Authorization: Bearer YOUR_AUTH_TOKEN" \
       -H "Content-Type: application/json" \
       -d '{
         "filters": { "key": "value" }
       }'

• Full Documentation: Datastore: Query

---

5. Count records in a Datastore

• 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):

  curl -X POST "https://api.verida.ai/api/rest/v1/ds/count/aHR0cHM6Ly9..." \
       -H "Authorization: Bearer YOUR_AUTH_TOKEN" \
       -H "Content-Type: application/json" \
       -d '{
         "filters": { "key": "value" }
       }'

• Full Documentation: Datastore Count

---

6. Watch a Datastore

• 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

• Full Documentation: Datastore: Watch

---

7. Delete a Record

• HTTP Method & Endpoint: DELETE /ds/{dsUrlEncoded}/{id}

• Summary: Remove a record permanently from a datastore.

• Credit Usage: 1 credit

• Scope: api:ds-delete

• Example:

  curl -X DELETE "https://api.verida.ai/api/rest/v1/ds/aHR0cHM6Ly9.../456" \
       -H "Authorization: Bearer YOUR_AUTH_TOKEN"

---

Databases

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.

1. Get a Record by ID

• 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:

  curl -X GET "https://api.verida.ai/api/rest/v1/db/myDatabase/123" \
       -H "Authorization: Bearer YOUR_AUTH_TOKEN"

• Full Documentation: Database: Get Record by ID

---

2. Create a Record

• HTTP Method & Endpoint: POST /db/{dbName}

• Summary: Insert a new record into the specified database.

• Credit Usage: 1 credit

• Scope: api:db-create

• Example:

  curl -X POST "https://api.verida.ai/api/rest/v1/db/myDatabase" \
       -H "Authorization: Bearer YOUR_AUTH_TOKEN" \
       -H "Content-Type: application/json" \
       -d '{
         "title": "First Entry",
         "content": "Hello World!"
       }'

---

3. Update a Record

• 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:

  curl -X PUT "https://api.verida.ai/api/rest/v1/db/myDatabase/123" \
       -H "Authorization: Bearer YOUR_AUTH_TOKEN" \
       -H "Content-Type: application/json" \
       -d '{
         "title": "Updated Title",
         "content": "Revised Content"
       }'

---

4. Query a Database

• 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:

  curl -X POST "https://api.verida.ai/api/rest/v1/db/query/myDatabase" \
       -H "Authorization: Bearer YOUR_AUTH_TOKEN" \
       -H "Content-Type: application/json" \
       -d '{
         "filters": { "status": "active" },
         "limit": 10
       }'

• Full Documentation: Database: Query

---

5. Count records in a Database

• 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:

  curl -X POST "https://api.verida.ai/api/rest/v1/db/count/myDatabase" \
       -H "Authorization: Bearer YOUR_AUTH_TOKEN" \
       -H "Content-Type: application/json" \
       -d '{
         "filters": { "status": "active" },
         "limit": 10
       }'

• Full Documentation: Database: Query

---

Best Practices

1. Secure Your Requests: Always include the Authorization: Bearer YOUR_AUTH_TOKEN header and ensure your application only requests the necessary scopes.

2. Understand Credit Costs: Each API call draws from your available credits. Optimize your queries and reduce unnecessary calls.

3. Use the Right Endpoint: Databases vs. Datastores have subtle differences. Identify which storage mechanism and endpoint best suit your application.

4. Leverage Real-Time Updates: Where possible, use datastore watching (GET /ds/watch) to keep application data in sync without continuous polling.

5. 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).