# OrgOrg API v1 — Thanks — instructions for AI agents

This document describes the Thanks endpoints of the OrgOrg v1 REST API. Fetch it from https://orgorg.com/docs/api/v1/thanks/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, ... }`.

## Thanks

Send peer recognition. Human-readable docs: https://orgorg.com/docs/api/v1/thanks

### Give Thanks

`POST /api/v1/thanks/give`

Give thanks from one user to another. By default a token can only send thanks as its owner; a token with the 'thanks:impersonate' scope (admin-granted) may set fromEmail to any active member of the org.

Parameters:

- `fromEmail` (string, required) — The email of the user giving thanks. By default this must match the token owner's email. To attribute thanks to someone else (e.g. an automated peer-bonus flow), the token needs the 'thanks:impersonate' scope, and the sender must be an active member of the org. The 'thanks:impersonate' scope can only be granted by an Administrator or Owner when creating the token.
- `toEmail` (string, required) — The email of the user receiving thanks.
- `message` (string, required) — The message of gratitude to deliver.

Example request:

```sh
curl -X POST "https://orgorg.com/api/v1/thanks/give" \
  -H "Authorization: Bearer $ORGORG_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "fromEmail": "user1@domain.com",
    "toEmail": "user2@domain.com",
    "message": "You're amazing! Thank you so much for creating an awesome API. 😂"
  }'
```

Response shape:

```ts
{
  message: string;
  delivered: boolean;
  url: string | null; // link to the delivered thanks (null if not delivered); viewing requires a signed-in session
  from: {
    email: string;
    displayName: string;
    manager: { email: string; displayName: string } | null; // direct manager
    managerChain: { email: string; displayName: string; depth: number }[]; // upward chain (direct manager first)
  };
  to: {
    email: string;
    displayName: string;
    manager: { email: string; displayName: string } | null;
    managerChain: { email: string; displayName: string; depth: number }[];
  };
}
```