# OrgOrg API v1 — Oncall — instructions for AI agents

This document describes the Oncall endpoints of the OrgOrg v1 REST API. Fetch it from https://orgorg.com/docs/api/v1/oncall/agents.md. The full API is documented at https://orgorg.com/docs/api/v1/agents.md.

## Basics

- Base URL: `https://orgorg.com`. All endpoint paths below are relative to it.
- Every request requires an `Authorization: Bearer <token>` header.
- `GET` endpoints take parameters in the URL query string. `POST` endpoints take a JSON body with a `Content-Type: application/json` header.
- All responses are JSON. A non-2xx status means the request failed; the body describes the problem.
- Endpoints are stable, but new response fields may be added without notice — ignore fields you do not recognize.

## Getting a token

Tokens are created by a signed-in user at https://orgorg.com/docs/credentials and inherit that user's permissions in their organization. If you do not have a token, ask your user to create one there. Verify a token works with:

```sh
curl "https://orgorg.com/api/v1/auth/test" \
  -H "Authorization: Bearer $ORGORG_API_TOKEN"
```

A valid token returns `{ "ok": true, ... }`.

## Oncall

Page oncall and inspect rotations. Human-readable docs: https://orgorg.com/docs/api/v1/oncall

### Page Oncall

`POST /api/v1/oncall/page`

Programatically paging on-call can be done with standard REST api calls. This can be especially useful if you have monitors that alert when certain thresholds are met. Here's an example of how you could automatically page on-call, using the JavaScript Fetch API.  Access tokens to page oncall must be created in Oncall settings page https://orgorg.com/oncall.

Parameters:

- `message` (string, required) — Message to send to on-call

Example request:

```sh
curl -X POST "https://orgorg.com/api/v1/oncall/page" \
  -H "Authorization: Bearer $ORGORG_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "A spike of 500 errors appeared in the logs, can you take a look?"
  }'
```

Response shape:

```ts
{
  status: string;
  message: string;
  totalTime: number;
}
```

### Get all active Oncalls

`GET /api/v1/oncall/list`

Get a list of all active oncall rotations, primary and secondary for each rotation, and a list of active incidents if any exist for each oncall.

Parameters: none.

Example request:

```sh
curl -X GET "https://orgorg.com/api/v1/oncall/list" \
  -H "Authorization: Bearer $ORGORG_API_TOKEN"
```

Response shape:

```ts
{
  id: string;
  name: string;
  description: string | null;
  activeShift?: {
    startDate?: Date;
    endDate?: Date;
    primary: {
      email: string;
      displayName: string;
      phone?: string;
    };
    secondary?: {
      email: string;
      displayName: string;
      phone?: string;
    };
  };
  incidents?: {
    id: number;
    onPoint: {
      email: string;
      displayName: string;
      phone?: string;
    };
    message: string;
    status: string;
    events: {
      id: number;
      profile: {
        email: string;
        displayName: string;
        phone?: string;
      };
      type: Clear | Alert | NotifyOnPoint | DuplicateAlert | Acknowledge | Escalate | AutoEscalate | MissingPhone | NoEscalationPossible | NoActiveShift | Note | UpdateOnPoint;
      channel:   Web | Sms | Voice | Slack | IncomingApi | OrgOrg;
      created: Date;
      message?: string;
      props?: NoteEventProps | UpdateOnPointEventProps | Object;
    }[];
    created: Date;
    slackChannel?: string;
    slackChannelName?: string;
    slackMessageId?: string;
  }[];
  created: Date;
}
```