Data API: Create, Retrieve, and Delete Data Objects

Use GET, POST, and DELETE /v1/data to manage the data objects in your account — create new items, retrieve them, and remove outdated records.

Data objects are the core building blocks of the Google platform. Each object represents a discrete piece of information — a document, a note, or a structured record — that you can store, search, and act upon through the API. The Data API gives you full lifecycle control: you can list all objects in your account with flexible sorting and pagination, create new objects with rich metadata and tags, and permanently delete records you no longer need. All write operations require the write scope on your API key.

GET /v1/data

Retrieve a paginated list of all data objects in your account, ordered by your chosen sort field. Use the page and limit parameters to work through large datasets efficiently.

Query Parameters

page · integer · default: "1"

The page number to retrieve. Starts at 1.

limit · integer · default: "20"

The number of items to return per page. Maximum is 100.

sort · string · default: "date"

The field by which results are ordered. Accepted values:

• date — orders by creation date, newest first (default)
• title — orders alphabetically by title

Example Request

cURL

curl https://api.google.com/v1/data \
  -H 'Authorization: Bearer YOUR_API_KEY'

Example Response

{
  "data": {
    "items": [
      {
        "id": "dat_abc123",
        "title": "Q1 Report",
        "type": "document",
        "created_at": "2024-03-01T08:00:00Z"
      }
    ],
    "total": 1
  }
}

Response Fields

items · array

An array of data objects belonging to your account, ordered by the sort parameter.

Show items[]

id · string

The unique identifier for the data object, prefixed with dat_.

title · string

The human-readable title of the data object.

type · string

The object type. One of document, note, or record.

created_at · string

The ISO 8601 timestamp at which the data object was created, in UTC.

total · integer

The total number of data objects in your account across all pages.

---

POST /v1/data

Create a new data object in your account. You can attach free-form content, an array of searchable tags, and arbitrary key-value metadata to every object you create. This endpoint requires write scope and returns a 201 Created response containing the newly created object.

Request Body

title · string · required

A short, descriptive title for the data object. This field is indexed for full-text search and displayed in search results.

type · string · required

The object type. Accepted values:

• document — a longer-form text artifact such as a report or article
• note — a brief, informal piece of text
• record — a structured entry, often used for tabular or log data

content · string

The main body text of the data object. This field is fully indexed for search and supports plain text. There is no enforced maximum length, but objects with very large content bodies may affect indexing latency.

tags · array

An array of string tags to associate with the object. Tags are indexed and can be used with the Search API’s filter parameter — for example, filter=tags:finance. Each tag must be a non-empty string.

metadata · object

An arbitrary key-value object for storing additional structured attributes alongside your data. Keys and values must both be strings. Metadata is not currently searchable but is returned in full on every object response.

Example Request

cURL

curl -X POST https://api.google.com/v1/data \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "title": "Q2 Report",
    "type": "document",
    "content": "This report covers Q2 financial performance...",
    "tags": ["finance", "quarterly"],
    "metadata": { "department": "finance", "author": "alice" }
  }'

Example Response

{
  "data": {
    "id": "dat_def456",
    "title": "Q2 Report",
    "type": "document",
    "content": "This report covers Q2 financial performance...",
    "tags": ["finance", "quarterly"],
    "metadata": { "department": "finance", "author": "alice" },
    "created_at": "2024-06-01T10:00:00Z"
  }
}

Response Fields

id · string

The unique identifier for the newly created data object, prefixed with dat_.

title · string

The title of the data object as provided in the request body.

type · string

The object type. One of document, note, or record.

content · string

The main body text of the data object, as provided in the request body.

tags · array

The array of string tags associated with the object.

metadata · object

The key-value metadata object attached to the data object.

created_at · string

The ISO 8601 timestamp at which the data object was created, in UTC.

After a successful POST, the new data object will be available via GET /v1/data immediately. However, it may take up to 30 seconds for the object to become searchable via GET /v1/search while the search index is updated.

---

DELETE /v1/data/

Permanently delete a data object from your account. Once deleted, the object and all of its associated content, tags, and metadata are removed and cannot be recovered. This endpoint requires write scope and returns 204 No Content on success with an empty response body.

Path Parameters

id · string · required

The unique identifier of the data object you want to delete, for example dat_abc123. You can obtain this from the GET /v1/data listing or from the response of a POST /v1/data request.

Example Request

cURL

curl -X DELETE https://api.google.com/v1/data/dat_abc123 \
  -H 'Authorization: Bearer YOUR_API_KEY'

A successful response returns HTTP 204 No Content with no body.

Response Fields

This endpoint returns no response body. A 204 No Content status code indicates the data object was successfully deleted.

Deletion is permanent and irreversible. There is no soft-delete or trash mechanism — once you issue a DELETE request, the object cannot be restored. If you need to preserve data for auditing or compliance purposes, export or archive the object before deleting it.