# API reference

> The grovs REST API: base URLs, request format, IDs and the resources you can call from your server.

Source: https://docs.grovs.io/docs/api-reference

## Introduction

Use the grovs REST API from your servers and scripts. Create links and read their metrics, manage segments and in-app messages, send transactional pushes, and pull your event data and audit log.

Every request and response body is JSON. Send `Content-Type: application/json` with a body.

Each endpoint names the credential it takes. See [Authentication](https://docs.grovs.io/docs/api-reference/authentication).

```bash
curl https://sdk.sqd.link/api/v1/sdk/metrics_for_project \
  -H "PROJECT-KEY: $GROVS_PROJECT_KEY" \
  -H "ENVIRONMENT: production"
```

## Base URLs

grovs answers on two hosts. Each endpoint's request example shows which one it uses.

| Host                                                                                                                                                                                                                                                                             | grovs Cloud            | Self-hosted                 |
| -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------- | --------------------------- |
| `sdk.`: [Links](https://docs.grovs.io/docs/api-reference/links), [Segments](https://docs.grovs.io/docs/api-reference/segments), [In-app messages](https://docs.grovs.io/docs/api-reference/in-app-messages), [Server push](https://docs.grovs.io/docs/api-reference/server-push) | `https://sdk.sqd.link` | `https://sdk.<SERVER_HOST>` |
| `api.`: [Event stream](https://docs.grovs.io/docs/api-reference/event-stream), [Audit log](https://docs.grovs.io/docs/api-reference/audit-log)                                                                                                                                   | `https://api.sqd.link` | `https://api.<SERVER_HOST>` |

Every path starts with `/api/v1`.

On a self-hosted install, `SERVER_HOST` is the bare app domain you set in `.env`, for example `grovs.example.com`. The backend derives the `api.` and `sdk.` hosts from it. See [Self-hosting](https://docs.grovs.io/docs/self-hosting).

```text
grovs Cloud
  https://api.sqd.link/api/v1/...
  https://sdk.sqd.link/api/v1/sdk/...

Self-hosted (SERVER_HOST=grovs.example.com)
  https://api.grovs.example.com/api/v1/...
  https://sdk.grovs.example.com/api/v1/sdk/...
```

## IDs

The `sdk.` endpoints need no ID in the path. The project key and the `ENVIRONMENT` header pick the project.

The `api.` endpoints take a numeric ID in the path:

- **Event stream:** `/api/v1/projects/{project_id}`. The ID of one environment, production or test. See [Find the project ID](https://docs.grovs.io/docs/api-reference/event-stream#find-the-project-id).
- **Audit log:** `/api/v1/instances/{instance_id}`. The log covers production and test together. See [Find the instance ID](https://docs.grovs.io/docs/api-reference/audit-log#find-the-instance-id).

Other IDs are short strings (hashids), such as a segment ID `gk3x` or a push campaign ID `k9Qx2`. Link IDs and audit log sequence numbers are integers. Each endpoint's parameters give the type it takes.

```text
/api/v1/projects/123/event_stream
                 ^^^
                 project ID (integer)

/api/v1/sdk/server/push/k9Qx2
                        ^^^^^
                        campaign ID (hashid)
```

## Versioning

The API version is part of the path: `/api/v1`. Fields may be added to responses within `v1`, so ignore keys you do not know.

Payloads you store on your side carry their own `schema_version`: the [event envelope](https://docs.grovs.io/docs/api-reference/event-stream#the-event-envelope) and [audit log events](https://docs.grovs.io/docs/api-reference/audit-log#the-audit-event-object). A rename or removal there comes as a new `schema_version`.

```json
{
  "schema_version": 1,
  "events": [],
  "next_after": 12,
  "next_before": 1
}
```

## Resources

| Resource                                                                    | What it does                                                                    | Credential            |
| --------------------------------------------------------------------------- | ------------------------------------------------------------------------------- | --------------------- |
| [Links](https://docs.grovs.io/docs/api-reference/links)                     | Generate a link. Read link details, link metrics and project metrics.           | Project key           |
| [Segments](https://docs.grovs.io/docs/api-reference/segments)               | Create, estimate, count and archive segments. Upload identifier lists.          | Project key           |
| [In-app messages](https://docs.grovs.io/docs/api-reference/in-app-messages) | Create, launch, pause and end in-app messages. Send a test and read the report. | Project key           |
| [Server push](https://docs.grovs.io/docs/api-reference/server-push)         | Send a transactional push and read its report.                                  | Project key           |
| [Event stream](https://docs.grovs.io/docs/api-reference/event-stream)       | Read the pull feed of analytics and purchase events.                            | Feed token (`est_`)   |
| [Audit log](https://docs.grovs.io/docs/api-reference/audit-log)             | Export the audit log to your SIEM.                                              | Export token (`aet_`) |

Dashboard push campaigns, journeys, smart banners and dashboards are managed in the dashboard.

A failed request returns an HTTP status code and, in most cases, a JSON body with an `error` message. See [Errors](https://docs.grovs.io/docs/api-reference/errors).

```json
{
  "error": "Link not found"
}
```