---
title: Overview
slug: overview
description: Public overview for the Agent Notifier API.
openapi_tags: [System]
---

# Agent Notifier API

Agent Notifier is the missing harness for agentic development. Agents keep working in the terminal, while developers receive timely iPhone/web notifications for progress, failures, approvals, links, files, and completion.

The shortest path is: create an account API key, run the installer in a repo, and let Copilot/Claude hooks report each agent run into a project timeline.

## Product links

| Purpose | URL |
|---|---|
| Web app and API keys | `https://notifier.aicrew.in/app` |
| Install guide | `https://notifier.aicrew.in/install` |
| Shareable Skill.md | `https://notifier.aicrew.in/skill.md` |
| Installer script | `https://notifier.aicrew.in/install.sh` |
| Pricing | `https://notifier.aicrew.in/pricing` |

Pricing is intentionally simple for launch: 100 free requests to try it out, then `$8/month` or `$80/year`.

## Base URLs

| Environment | Base URL |
|---|---|
| Production API root | `https://notifier.aicrew.in/api` |
| Production v1 base | `https://notifier.aicrew.in/api/v1` |
| Local API root | `http://localhost:8080` |
| Local v1 base | `http://localhost:8080/v1` |

Production traffic should use `/api/v1/...`. Legacy direct `/v1/...` routes may still work, but new docs and examples should prefer the canonical `/api/v1` prefix.

## Core concepts

- **Project** — a logical sender such as a repo, agent, workflow, or service.
- **Session** — a time-boxed run within a project, commonly used for long-running agent work.
- **Notification** — a typed event: `alert`, `progress`, `session_start`, `session_end`, `url`, or `file`.
- **Substance fields** — optional notification fields (`event`, `tool_name`, `command`, `prompt`, `file_paths`, `parent_id`, `subagent_id`, `status`) used by iOS/admin to render the useful content instead of parsing boilerplate from the message body.
- **API key** — an account-scoped or legacy project-scoped secret used by agents in the `X-API-Key` header.
- **Action response** — a button tap recorded by the app and optionally forwarded to a project webhook.
- **Approval** — a first-class HITL request that sends a decision notification and can wait/stream until the user decides.
- **Install skill** — a shareable `Skill.md` that tells agents how to set up hooks, local env, and CLAUDE.md guidance without committing secrets.

## Agent harness quick install

Run this from the repository you want monitored after creating an API key:

```bash
export AGENT_NOTIFIER_API_KEY="an_key_REPLACE_WITH_YOUR_KEY"
export AGENT_NOTIFIER_PROJECT="my-repo"
curl -fsSL https://notifier.aicrew.in/install.sh | bash
```

The installer downloads the canonical hook runner, scaffolds `.github/hooks/hooks.json` and `.claude/settings.json`, appends a local Agent Notifier note to `CLAUDE.md`, and writes secrets only to `.env.local`.

## Most-used endpoints

| Purpose | Method and path | Auth |
|---|---|---|
| Send a notification | `POST /v1/messages` | `X-API-Key` |
| Send/wait for approval | `POST /v1/approvals` | `X-API-Key` |
| Upload media | `POST /v1/media` | `X-API-Key` |
| Create/list sessions | `POST /v1/sessions`, `GET /v1/sessions` | `X-API-Key` |
| Poll action responses | `GET /v1/action-responses` | `X-API-Key` |
| Stream action responses | `GET /v1/action-responses/stream` | `X-API-Key` |
| List feed items | `GET /v1/notifications` | Bearer JWT |
| Create projects | `POST /v1/projects` | Bearer JWT |
| Get exact project stats | `GET /v1/projects/{id}/stats` | Bearer JWT |
| Create account API keys | `POST /v1/api-keys` | Bearer JWT |
| Revoke API keys | `DELETE /v1/api-keys/{id}` | Bearer JWT |
| Rotate API keys by ID | `POST /v1/api-keys/{id}/rotate` | Bearer JWT |
| Rotate legacy project API keys | `POST /v1/api-keys/rotate` | Bearer JWT |
| Record action taps | `POST /v1/actions` | Bearer JWT |
| Health check | `GET /health` | None |
| OpenAPI spec | `GET /openapi.yaml` | None |

## Honest unsupported surfaces

The OpenAPI spec includes several future-facing endpoints so clients can handle them explicitly, but they are not launch claims:

- `POST /v1/auth/google` returns `501 unsupported`; real Google login is not shipped.
- `POST /v1/subscriptions/verify` returns `503 unconfigured` until Apple JWS verification is configured; it does not prove paid entitlement today.
- `POST /v1/subscriptions/stripe/checkout` returns `501 unsupported`; Stripe checkout is not available today.

## Documentation pages

- [Quickstart](quickstart.md)
- [Auth and API keys](auth.md)
- [Messages](messages.md)
- [Hooks](hooks.md)
- [Media](media.md)
- [Actions and webhooks](actions-webhooks.md)
- [Errors and rate limits](errors-rate-limits.md)

For exact request and response schemas, use the OpenAPI reference at `/api/docs/reference` and the machine-readable spec at `/api/openapi.yaml`.