# Agent Push Kit

Agent Push Kit is a searchable notification inbox for software, with an iPhone app for humans and complete REST, MCP, skill, and SDK access for agents.

- [Getting started](./getting-started.md)
- [API reference](./api.md)
- [SDKs](./sdks.md)
- [MCP](./mcp.md)
- [Agent skill](./skill.md)

## Authentication

- `apk_…` organization keys are limited to application event ingestion.
- Agent Push Kit login JWTs authenticate the human app.
- Named `apt_…` agent tokens provide the same user-level access and organization-role enforcement as the user who created them. They do not expire and can be revoked immediately.

Never print, commit, or place a raw key or token in a URL.


---

# Getting started

## Send an application notification

1. Register or log in at <https://agentpushkit.com>.
2. In Settings, choose the customer account and regenerate its application API key. Copy the `apk_…` value; it is shown only once.
3. Send an event:

```bash
curl https://api.chatdna.co/agent-push-kit/v1/events \
  -H 'Authorization: Bearer apk_YOUR_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "service": "billing",
    "type": "invoice.paid",
    "title": "Invoice paid",
    "body": "Acme paid invoice #1042",
    "externalId": "invoice_1042_paid",
    "actionUrl": "https://example.com/invoices/1042",
    "metadata": {"invoiceId": "1042", "amount": 4900}
  }'
```

`service`, `type`, `title`, and `body` are required. Service names and exact notification types require no configuration. Reusing an `externalId` within one service returns the original event and does not send another push.

## Connect an agent

1. Open <https://agentpushkit.com/connect-agent> while logged in.
2. Create and name an agent token.
3. Copy the `apt_…` token once.
4. Use the generated setup prompt, install the [skill](./skill.md), connect [MCP](./mcp.md), or install an [SDK](./sdks.md).

An agent token can perform every authenticated product operation and is subject to the same owner/member checks as its creator.


---

# API reference

Base URL: `https://api.chatdna.co/agent-push-kit/v1`

Canonical contracts:

- [OpenAPI YAML](/openapi.yaml)
- [OpenAPI JSON](/openapi.json)
- [Interactive web reference](https://agentpushkit.com/docs/api)

## Public authentication operations

- `POST /auth/register`
- `POST /auth/login`
- `POST /auth/google`
- `POST /auth/apple`
- `POST /auth/password-reset/request`
- `POST /auth/password-reset/complete`

## Authenticated product operations

- Current account: `GET /me`, `DELETE /me`
- Customer accounts: list/create organizations, list/add registered members, rotate an ingestion key
- Agent tokens: list/create/revoke
- Inbox: list, Boolean-filter search, detail, services, and exact notification types
- Push controls: service defaults and exact-type overrides
- Devices: register and disable an APNs installation

These operations accept a login JWT or `apt_…` agent token. Organization membership and owner-only operations are enforced identically for both.

## Application ingestion

`POST /events` accepts an `apk_…` organization key. It can only store an event and attempt eligible push deliveries.

## Errors

Errors use Nest's JSON error envelope with `statusCode`, `message`, and usually `error`. Treat `401` as a missing, invalid, or revoked credential; `403` as an owner-only denial; and `404` as either absence or an inaccessible customer-account resource.


---

# SDKs

All SDKs are generated from OpenAPI version `0.1.0`, use the MIT license, and share the same semantic version. Generated repositories are outputs; the OpenAPI document in the Agent Push Kit monorepo is canonical.

## Primary packages

| Language | Installation |
| --- | --- |
| TypeScript / JavaScript | `npm install agent-push-kit` |
| Python | `pip install agent-push-kit` |
| PHP | `composer require agentpushkit/client` |
| Ruby | `gem install agent_push_kit` |
| Go | `go get github.com/JustinBStrong/agent-push-kit-go` |
| Swift 6 | Add `https://github.com/JustinBStrong/agent-push-kit-swift` in Swift Package Manager |
| Java / Kotlin / Scala | Maven group `com.agentpushkit` |
| C# | `dotnet add package AgentPushKit` |
| Rust | `cargo add agent-push-kit` |
| Dart | `dart pub add agent_push_kit` |
| Elixir | Add `{:agent_push_kit, "~> 0.1.0"}` |
| Clojure | Maven coordinate `com.agentpushkit/agent-push-kit` |
| Perl | `cpanm AgentPushKit::Client` |
| Haskell | Add `agent-push-kit` to dependencies |
| R | Install from the Agent Push Kit R-universe |

C, C++, Bash, Objective-C, and other experimental generators are release archives until their generator output passes the stable build and smoke-test bar.

See [/sdks/manifest.json](/sdks/manifest.json) for machine-readable package names, repositories, versions, status, checksums, install commands, and the current release-archive manifest. Every release archive is also mirrored on this site under `/sdks/releases/v<version>/` with SHA-256 checksums.


---

# MCP

Agent Push Kit offers the same semantic tools through a hosted stateless Streamable HTTP server and an npm stdio server. Both require a named `apt_…` agent token.

## Hosted Streamable HTTP

- URL: `https://api.chatdna.co/agent-push-kit/v1/mcp`
- Header: `Authorization: Bearer apt_YOUR_TOKEN`

```json
{
  "mcpServers": {
    "agent-push-kit": {
      "url": "https://api.chatdna.co/agent-push-kit/v1/mcp",
      "headers": {"Authorization": "Bearer apt_YOUR_TOKEN"}
    }
  }
}
```

## npm stdio

```bash
AGENT_PUSH_KIT_TOKEN=apt_YOUR_TOKEN npx -y agent-push-kit-mcp
```

Set `AGENT_PUSH_KIT_API_BASE` only when targeting a development or self-hosted CAM API.

## Tools

The server exposes current-account retrieval/deletion; customer-account listing/creation and member listing/addition; agent-token listing/creation/revocation; ingestion-key rotation; event sending/listing/search/detail; service and type discovery; service/type preference management; and device registration/removal.

Destructive and key-rotation tools are marked in MCP metadata. Registration, login, provider login, and password reset remain public REST/SDK operations because an authenticated MCP connection cannot exist until credentials exist.

Registry metadata: [/mcp/server.json](/mcp/server.json)


---

# Agent skill

The open `agent-push-kit` skill teaches an agent to bootstrap access, select REST/MCP/SDK workflows, add notifications to an application, investigate events, and manage notification preferences.

## Direct installation

```bash
git clone https://github.com/JustinBStrong/agent-push-kit-skill \
  .agents/skills/agent-push-kit
```

## Codex

Install the skill directory at `~/.codex/skills/agent-push-kit`, or install from the Git repository using Codex's skill installer.

## Claude-compatible clients

Use the repository directory or download [/skills/agent-push-kit.zip](/skills/agent-push-kit.zip) and extract it into the client's skills directory. Reproducible installs may pin the [0.1.0 archive](/skills/releases/v0.1.0/agent-push-kit-0.1.0.zip).

- [SKILL.md](/skills/agent-push-kit/SKILL.md)
- [Skill archive](/skills/agent-push-kit.zip)
- [GitHub repository](https://github.com/JustinBStrong/agent-push-kit-skill)


---

# Agent Push Kit agent onboarding

Read <https://agentpushkit.com/llms-full.txt> before changing an integration.

## Connect

Ask the human to open <https://agentpushkit.com/connect-agent>, create a named agent token, and provide the generated setup prompt. Store its `apt_…` token as `AGENT_PUSH_KIT_TOKEN`. Never print or commit it.

Then choose one interface:

1. Hosted MCP: `https://api.chatdna.co/agent-push-kit/v1/mcp` with `Authorization: Bearer apt_…`.
2. Stdio MCP: `npx -y agent-push-kit-mcp` with `AGENT_PUSH_KIT_TOKEN` in the environment.
3. SDK: select a package from <https://agentpushkit.com/sdks/manifest.json>.
4. REST: generate against <https://agentpushkit.com/openapi.json>.

Install the Agent Push Kit skill from <https://agentpushkit.com/skills/agent-push-kit.zip> for workflow guidance.

## Bootstrap an application

List customer accounts and choose the intended account. Rotate its organization ingestion key only when no usable key is available, because rotation immediately invalidates the old key. Store the returned `apk_…` value in the application's secret manager, then send events to `POST /events`.

Use stable dot-separated types such as `user.signup` or `billing.payment-failed`. Put service-specific detail in the single `metadata` object. Use `externalId` to prevent duplicate pushes and `actionUrl` when a human should open a relevant workflow.

## Investigate

Start with simple event listing and text search. Use the Boolean filter tree only when service/type/title/body conditions require AND, OR, or NOT. Retrieve event detail to inspect metadata.

## Notification controls

Preferences only affect future pushes; muted events stay in the inbox. A service default may be overridden by an exact type. Removing the override restores inheritance.


---

# Complete operation index
- POST /auth/register — Create a user and first customer account (register)
- POST /auth/login — Log in with email and password (loginWithPassword)
- POST /auth/google — Log in or attach an account using a verified Google ID token (loginWithGoogle)
- POST /auth/apple — Log in or attach an account using a Sign in with Apple identity token (loginWithApple)
- POST /auth/password-reset/request — Email a single-use password reset token (requestPasswordReset)
- POST /auth/password-reset/complete — Choose a new password and log in (completePasswordReset)
- GET /me — Get the current user and customer accounts (getCurrentAccount)
- DELETE /me — Delete the current user and customer accounts they own (deleteCurrentAccount)
- GET /organizations — List customer accounts available to the current user (listOrganizations)
- POST /organizations — Create another Agent Push Kit customer account (createOrganization)
- GET /organizations/{organizationId}/members — List members of a customer account (listOrganizationMembers)
- POST /organizations/{organizationId}/members — Add an already-registered user to a customer account (addOrganizationMember)
- POST /organizations/{organizationId}/api-key/regenerate — Rotate the application event-ingestion key (regenerateOrganizationApiKey)
- GET /agent-tokens — List agent access tokens without their secrets (listAgentTokens)
- POST /agent-tokens — Create a named non-expiring agent token (createAgentToken)
- DELETE /agent-tokens/{tokenId} — Revoke one of the current user's agent tokens (revokeAgentToken)
- POST /events — Send an event using an application ingestion key (sendEvent)
- GET /organizations/{organizationId}/events — List a paginated inbox (listEvents)
- POST /organizations/{organizationId}/events — Send an event as an authenticated user or agent (sendEventAsUser)
- POST /organizations/{organizationId}/events/search — Search events with a validated Boolean filter tree (searchEvents)
- GET /organizations/{organizationId}/events/{eventId} — Get one event including metadata (getEvent)
- GET /organizations/{organizationId}/services — List services discovered from ingested events (listServices)
- GET /organizations/{organizationId}/types — List distinct notification types (listNotificationTypes)
- GET /organizations/{organizationId}/preferences — List service defaults and exact-type overrides (listPreferences)
- PUT /services/{serviceId}/preference — Enable or disable pushes for a service by default (setServicePreference)
- PUT /services/{serviceId}/types/{type}/preference — Override push delivery for one exact notification type (setTypePreference)
- DELETE /services/{serviceId}/types/{type}/preference — Remove an exact-type override so it inherits the service default (removeTypePreference)
- POST /devices — Register or refresh an APNs device (registerDevice)
- DELETE /devices/{installationId} — Disable push delivery to one installation (removeDevice)
- GET /web-push/configuration — Get browser push availability and its public VAPID key (getWebPushConfiguration)
- POST /web-push/subscriptions — Register or refresh a browser push subscription (registerWebPushSubscription)
- DELETE /web-push/subscriptions/{subscriptionId} — Disable a browser push subscription (removeWebPushSubscription)
- GET /health — Check Agent Push Kit API health (getHealth)
- POST /mcp — Connect through stateless MCP Streamable HTTP (callMcp)