> ## Documentation Index
> Fetch the complete documentation index at: https://docs.newport.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Data Records API: Create, Query, Update, and Delete Records

> The Data API lets you create, read, update, and delete records in your Google workspace with full support for filtering, sorting, and pagination.

The Data API is the backbone of your Google workspace, giving you structured access to every record your team creates and manages. From simple documents to richly tagged, field-rich entries, you can query across your entire dataset with powerful filters, sort results by any field, and perform bulk operations to keep large collections in sync. All endpoints are authenticated via Bearer token and return JSON.

***

## List Records

Retrieve a filtered, sorted, and paginated list of records from your workspace.

**`GET https://api.google.com/v1/data`**

### Query Parameters

<ParamField query="type" type="string">
  Filter records by type (e.g., `document`, `task`, `note`).
</ParamField>

<ParamField query="status" type="string">
  Filter by record status. Common values: `active`, `archived`, `draft`.
</ParamField>

<ParamField query="page" type="integer">
  Page number to retrieve. Defaults to `1`.
</ParamField>

<ParamField query="per_page" type="integer" default={20}>
  Number of records to return per page. Defaults to `20`. Maximum is `100`.
</ParamField>

<ParamField query="sort" type="string">
  Field name to sort results by. Common values: `created_at`, `updated_at`, `name`.
</ParamField>

<ParamField query="order" type="string">
  Sort direction. Accepted values: `asc`, `desc`. Defaults to `asc`.
</ParamField>

<ParamField query="q" type="string">
  Full-text search query. Searches across record names and field values.
</ParamField>

### Example Request

```bash theme={null}
curl -X GET "https://api.google.com/v1/data?type=document&status=active&sort=created_at&order=desc" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

### Example Response

```json theme={null}
{
  "success": true,
  "data": [
    {
      "id": "rec_abc123",
      "name": "Q1 Report",
      "type": "document",
      "status": "active",
      "fields": {
        "priority": "high",
        "owner": "jane@example.com"
      },
      "tags": ["finance", "quarterly"],
      "created_at": "2024-03-01T09:00:00Z",
      "updated_at": "2024-03-05T14:30:00Z"
    },
    {
      "id": "rec_def456",
      "name": "Product Roadmap",
      "type": "document",
      "status": "active",
      "fields": {
        "priority": "medium",
        "owner": "alex@example.com"
      },
      "tags": ["product", "planning"],
      "created_at": "2024-02-20T11:15:00Z",
      "updated_at": "2024-03-08T10:00:00Z"
    }
  ],
  "meta": { "page": 1, "per_page": 20, "total": 87 }
}
```

***

## Get Record

Fetch a single record by its unique ID, including all fields and tags.

**`GET https://api.google.com/v1/data/:id`**

### Path Parameters

<ParamField path="id" type="string" required>
  The unique identifier of the record to retrieve (e.g., `rec_abc123`).
</ParamField>

### Example Request

```bash theme={null}
curl -X GET "https://api.google.com/v1/data/rec_abc123" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

### Example Response

```json theme={null}
{
  "success": true,
  "data": {
    "id": "rec_abc123",
    "name": "Q1 Report",
    "type": "document",
    "status": "active",
    "fields": {
      "priority": "high",
      "owner": "jane@example.com"
    },
    "tags": ["finance", "quarterly"],
    "created_at": "2024-03-01T09:00:00Z",
    "updated_at": "2024-03-05T14:30:00Z"
  }
}
```

***

## Create Record

Add a new record to your workspace. You can include custom key-value fields and any number of tags to keep records organized.

**`POST https://api.google.com/v1/data`**

### Body Parameters

<ParamField body="name" type="string" required>
  A human-readable name for the record.
</ParamField>

<ParamField body="type" type="string" required>
  The record type (e.g., `document`, `task`, `note`). Used for filtering and categorization.
</ParamField>

<ParamField body="fields" type="object">
  An optional object of custom key-value pairs to attach to the record. Values must be strings.
</ParamField>

<ParamField body="tags" type="array">
  An optional array of string tags for labeling and grouping records.
</ParamField>

### Example Request

```bash theme={null}
curl -X POST https://api.google.com/v1/data \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Q1 Report",
    "type": "document",
    "fields": {
      "status": "draft",
      "priority": "high"
    },
    "tags": ["finance", "quarterly"]
  }'
```

### Example Response

```json theme={null}
{
  "success": true,
  "data": {
    "id": "rec_abc123",
    "name": "Q1 Report",
    "type": "document",
    "status": "active",
    "fields": {
      "status": "draft",
      "priority": "high"
    },
    "tags": ["finance", "quarterly"],
    "created_at": "2024-06-01T12:00:00Z",
    "updated_at": "2024-06-01T12:00:00Z"
  }
}
```

<Tip>
  Use consistent `type` values across your workspace to make filtering and reporting more effective. Consider establishing a naming convention for your team before you start creating records at scale.
</Tip>

***

## Update Record

Apply partial updates to an existing record. You only need to include the fields you want to change — any omitted fields retain their current values.

**`PATCH https://api.google.com/v1/data/:id`**

### Path Parameters

<ParamField path="id" type="string" required>
  The unique identifier of the record to update.
</ParamField>

### Body Parameters

<ParamField body="name" type="string">
  Updated name for the record.
</ParamField>

<ParamField body="fields" type="object">
  Updated custom fields. Provided keys are merged with existing fields; existing keys not mentioned are preserved.
</ParamField>

<ParamField body="tags" type="array">
  Updated tags array. This fully replaces the existing tags list.
</ParamField>

<ParamField body="status" type="string">
  Updated status for the record (e.g., `active`, `archived`, `draft`).
</ParamField>

### Example Request

```bash theme={null}
curl -X PATCH "https://api.google.com/v1/data/rec_abc123" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "fields": {
      "status": "final",
      "reviewed_by": "alex@example.com"
    },
    "tags": ["finance", "quarterly", "approved"]
  }'
```

### Example Response

```json theme={null}
{
  "success": true,
  "data": {
    "id": "rec_abc123",
    "name": "Q1 Report",
    "type": "document",
    "status": "active",
    "fields": {
      "status": "final",
      "priority": "high",
      "reviewed_by": "alex@example.com"
    },
    "tags": ["finance", "quarterly", "approved"],
    "created_at": "2024-03-01T09:00:00Z",
    "updated_at": "2024-06-01T15:45:00Z"
  }
}
```

***

## Delete Record

Permanently delete a single record from your workspace.

**`DELETE https://api.google.com/v1/data/:id`**

<Warning>
  Record deletion is permanent and cannot be undone. All fields, tags, and associated metadata are immediately removed. If you want to retain the data but remove it from active views, consider setting `status` to `archived` via the Update Record endpoint instead.
</Warning>

### Path Parameters

<ParamField path="id" type="string" required>
  The unique identifier of the record to delete.
</ParamField>

### Example Request

```bash theme={null}
curl -X DELETE "https://api.google.com/v1/data/rec_abc123" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

A successful deletion returns HTTP `204 No Content` with an empty body.

***

## Bulk Operations

When you need to create or delete many records at once, bulk endpoints let you perform those operations in a single API call rather than looping through individual requests.

### Bulk Create

Create multiple records in one request by sending an array of record objects. The response contains an array of the newly created records in the same order.

**`POST https://api.google.com/v1/data/bulk-create`**

#### Example Request

```bash theme={null}
curl -X POST "https://api.google.com/v1/data/bulk-create" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "records": [
      {
        "name": "March Expenses",
        "type": "document",
        "fields": { "status": "draft" },
        "tags": ["finance"]
      },
      {
        "name": "April Expenses",
        "type": "document",
        "fields": { "status": "draft" },
        "tags": ["finance"]
      }
    ]
  }'
```

#### Example Response

```json theme={null}
{
  "success": true,
  "data": [
    {
      "id": "rec_ghi789",
      "name": "March Expenses",
      "type": "document",
      "status": "active",
      "fields": { "status": "draft" },
      "tags": ["finance"],
      "created_at": "2024-06-01T16:00:00Z",
      "updated_at": "2024-06-01T16:00:00Z"
    },
    {
      "id": "rec_jkl012",
      "name": "April Expenses",
      "type": "document",
      "status": "active",
      "fields": { "status": "draft" },
      "tags": ["finance"],
      "created_at": "2024-06-01T16:00:00Z",
      "updated_at": "2024-06-01T16:00:00Z"
    }
  ],
  "meta": { "created": 2 }
}
```

### Bulk Delete

Delete multiple records in one request by providing an array of record IDs.

**`DELETE https://api.google.com/v1/data/bulk-delete`**

<Warning>
  Bulk deletion is permanent. All specified records and their associated data will be immediately and irreversibly removed.
</Warning>

#### Example Request

```bash theme={null}
curl -X DELETE "https://api.google.com/v1/data/bulk-delete" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "ids": ["rec_ghi789", "rec_jkl012", "rec_mno345"]
  }'
```

#### Example Response

```json theme={null}
{
  "success": true,
  "meta": {
    "deleted": 3,
    "failed": 0
  }
}
```

***

## Error Reference

<AccordionGroup>
  <Accordion title="400 Bad Request">
    The request body is missing required fields (`name` or `type`) or contains invalid values. Check the request structure and try again.
  </Accordion>

  <Accordion title="401 Unauthorized">
    Your API key is missing or invalid. Ensure you include a valid Bearer token in the `Authorization` header.
  </Accordion>

  <Accordion title="404 Not Found">
    No record exists with the specified `id`. Verify the ID is correct.
  </Accordion>

  <Accordion title="422 Unprocessable Entity">
    The request is well-formed but contains semantic errors, such as unrecognized field types or empty required values.
  </Accordion>

  <Accordion title="429 Too Many Requests">
    You have exceeded the API rate limit. Wait before retrying. Check the `Retry-After` response header for the cooldown period.
  </Accordion>
</AccordionGroup>