> For the complete documentation index, see [llms.txt](https://docs.zero.inc/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.zero.inc/developers/api/introduction.md).

# Introduction

This page covers the mechanics you need before writing any request: the base URL, authentication, how to filter and page through results, and the difference between deleting and archiving.

{% hint style="info" %}
The Zero API is currently in beta. Contact the Zero team to request access.
{% endhint %}

## Base URL

All API requests should be made to:

```
https://api.zero.inc
```

## Authentication

All API requests require a Bearer token in the `Authorization` header:

```
Authorization: Bearer <your-api-token>
```

Create a key in **Settings → Connections → API keys**: under **Personal API keys**, **Generate API key**, then a name and an expiry. Copy it when it appears — you will not see it again. The same page shows the **Workspace ID** you pass as `workspaceId`.

## Quick Start

Two requests to get oriented:

{% stepper %}
{% step %}

### Get your workspace ID

Everything else needs a workspace ID, so fetch yours first:

```bash
curl -X GET "https://api.zero.inc/api/workspaces?fields=id,name" \
  -H "Authorization: Bearer YOUR_API_TOKEN"
```

{% endstep %}

{% step %}

### Use the workspace ID in requests

Then pass it along:

```bash
curl -X GET "https://api.zero.inc/api/companies?workspaceId=WORKSPACE_UUID&limit=10" \
  -H "Authorization: Bearer YOUR_API_TOKEN"
```

{% endstep %}
{% endstepper %}

## Query Parameters

All `GET` endpoints support the following query parameters for filtering and pagination:

| Parameter | Type        | Default   | Description                                |
| --------- | ----------- | --------- | ------------------------------------------ |
| `fields`  | string      | `*` (all) | Comma-separated list of fields to return   |
| `where`   | JSON string | —         | Filter conditions                          |
| `limit`   | number      | `100`     | Maximum records to return                  |
| `offset`  | number      | `0`       | Pagination offset                          |
| `orderBy` | JSON string | —         | Sort order, e.g. `{"name":"asc"}`          |
| `groupBy` | string      | —         | Comma-separated list of fields to group by |

### Selecting Fields

Ask only for the fields you need:

```bash
curl "https://api.zero.inc/api/contacts?fields=id,name,email,title"
```

### Including Related Data

Dot notation in `fields` pulls in related objects: name one field (`company.name`) or use `.*` for the whole thing (`quotes.*`). To-one relations come back as an object, to-many as an array.

```bash
# Get contacts with their company information
curl "https://api.zero.inc/api/contacts?fields=id,name,email,company.name,company.domain"

# Get deals with company and contacts
curl "https://api.zero.inc/api/deals?fields=id,name,value,company.name,contacts.name"
```

### Filtering with `where`

`where` takes a JSON string:

```bash
curl 'https://api.zero.inc/api/companies?where={"workspaceId":"your-workspace-uuid"}'
```

Top-level conditions are combined with AND; use `$or` for OR. Which operators apply depends on the field type — `$eq`, `$not`, `$in`, `$contains`, `$startsWith`, `$exists` for text, `$gt` / `$gte` / `$lt` / `$lte` for numbers and dates, `$includes` for array fields. Date filters also accept relative macros such as `-7d` or `now()`. The API Reference lists the full set for each field type.

### Sorting with `orderBy`

Sort with `orderBy`:

```bash
curl 'https://api.zero.inc/api/deals?orderBy={"value":"desc"}'
```

## Response Format

Every endpoint returns the same shape:

```json
{
  "data": [...],
  "total": 42
}
```

For a single record — create, update — `data` is the record itself:

```json
{
  "data": {
    "id": "uuid",
    "name": "Acme Inc"
  }
}
```

## Deleting Records

Deleting comes in two flavours, and archiving is almost always the one you want:

```bash
# Soft delete (archive) - record can be recovered
curl -X DELETE "https://api.zero.inc/api/companies/COMPANY_UUID?archive=true" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

# Hard delete - permanent removal
curl -X DELETE "https://api.zero.inc/api/companies/COMPANY_UUID" \
  -H "Authorization: Bearer YOUR_API_TOKEN"
```

Archived records keep their history and can be restored by setting `archived` back to false. A hard delete cannot be undone.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.zero.inc/developers/api/introduction.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.