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.
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, Segments, In-app messages, Server push | https://sdk.sqd.link | https://sdk.<SERVER_HOST> |
api.: Event stream, 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.
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. - Audit log:
/api/v1/instances/{instance_id}. The log covers production and test together. See 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.
/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 and audit log events. A rename or removal there comes as a new schema_version.
{
"schema_version": 1,
"events": [],
"next_after": 12,
"next_before": 1
}Resources
| Resource | What it does | Credential |
|---|---|---|
| Links | Generate a link. Read link details, link metrics and project metrics. | Project key |
| Segments | Create, estimate, count and archive segments. Upload identifier lists. | Project key |
| In-app messages | Create, launch, pause and end in-app messages. Send a test and read the report. | Project key |
| Server push | Send a transactional push and read its report. | Project key |
| Event stream | Read the pull feed of analytics and purchase events. | Feed token (est_) |
| 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.
{
"error": "Link not found"
}