---
title: Identity, spec & batch
description: GET /me to verify a credential, the public OpenAPI document, the monitor-type catalog endpoint, and POST /batch to run up to 20 operations in one request.
canonical: https://watchfor.io/docs/api/meta
---

# Identity, spec & batch

GET /me to verify a credential, the public OpenAPI document, the monitor-type catalog endpoint, and POST /batch to run up to 20 operations in one request.

Small endpoints that support everything else: identify the credential
you are using, fetch the machine-readable contract, and bundle several
calls into one round trip.

| Method | Path | Scope | operationId |
| --- | --- | --- | --- |
| GET | `/v1/me` | read | `getMe` |
| GET | `/v1/openapi.json` | none | `getOpenApiSpec` |
| GET | `/v1/meta/monitor-types` | none | `listMonitorTypes` |
| POST | `/v1/batch` | per sub-operation | `batchOperations` |

## Identify the credential

`GET /v1/me` — the "does my auth work?" call. Returns the organization
the credential resolves to and its effective scope. Works for API keys
and OAuth tokens alike.

```bash
curl https://watchfor.io/api/v1/me \
  -H "Authorization: Bearer wf_live_YOUR_KEY"
```

```json
{
  "object": "api_key_identity",
  "organization": { "id": "6f0a…", "name": "Acme Cloud", "slug": "acme-cloud" },
  "scope": "read"
}
```

`scope` is `read` or `write`. For OAuth tokens it is `write` only when
the token was granted the `write` scope. See
[Authentication](/docs/api/authentication).

## OpenAPI document

`GET /v1/openapi.json` — the OpenAPI 3.1 description of every operation,
schema, parameter and error shape. Public, no key needed, cached for an
hour. Also served at `/openapi.json` and `/.well-known/openapi.json`.
Every operation declares a stable `operationId`, and every authenticated
one an `x-required-scope` (the public spec, the public type catalog and
`POST /batch` — which inherits its sub-operations' scopes — carry none);
list envelopes are named component schemas (`MonitorList`,
`IncidentList`, …) so generated clients get typed pages.

## Monitor type catalog

`GET /v1/meta/monitor-types` — every monitor type with its label,
description, target format and example, the default alert rules the
system seeds, the alert metrics you can build rules from and the config
fields it accepts. Public, no key needed. The top-level `operators`
array lists the comparison operators valid for numeric metrics. The
human-readable rendering is the [Monitor types reference](/docs/api/monitor-types).

## Batch

`POST /v1/batch` — run up to **20** API operations in one request. Each
operation is executed against `/api/v1` with the same credential you
sent, so scopes, validation and rate limits apply per sub-operation
exactly as for direct calls (each sub-operation consumes one request from
your budget). Only `Authorization` and `Content-Type` are forwarded — an
`Idempotency-Key` on the batch request does **not** protect its
sub-operations, so send creating writes directly when you need replay
protection. Results come back as a parallel array in request order; a
failing sub-operation does not abort the others.

```bash
curl -X POST https://watchfor.io/api/v1/batch \
  -H "Authorization: Bearer wf_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "operations": [
      { "method": "GET", "path": "/summary" },
      { "method": "GET", "path": "/monitors?status=down&limit=5" },
      { "method": "POST", "path": "/incidents/19351/acknowledge" }
    ]
  }'
```

```json
{
  "object": "batch_result",
  "results": [
    { "status": 200, "body": { "object": "summary", "…": "…" } },
    { "status": 200, "body": { "object": "list", "data": [], "has_more": false, "next_cursor": null } },
    { "status": 409, "body": { "error": { "code": "conflict", "message": "Cannot acknowledge a resolved incident" } } }
  ]
}
```

Rules:

- `operations` is required (a bare JSON array is also accepted);
  1–20 entries, each `{ "method", "path", "body"? }`.
- `method` is one of `GET`, `POST`, `PATCH`, `PUT`, `DELETE`; `path` is a
  relative `/api/v1` sub-path starting with `/` (query strings allowed).
  Absolute URLs, `..` and `/batch` itself are rejected with a per-item
  `400`.
- `body` is sent as JSON for non-GET operations.
- The batch endpoint itself needs a Bearer header (`401` otherwise); the
  credential is validated by each sub-operation, so an invalid key yields
  `401` items rather than a top-level error.
- A sub-request that cannot be executed at all returns
  `{ "status": 502, "body": { "error": { "code": "internal_error", … } } }`.

Use batch for fan-out reads (several monitors' uptime at once) or a
handful of related writes; for large bulk pause/resume/delete use
[`POST /v1/monitors/bulk`](/docs/api/monitors#bulk-operations).

---

Canonical page: https://watchfor.io/docs/api/meta · All docs: https://watchfor.io/docs · Site guide: https://watchfor.io/llms.txt