# Neotask API Reference

Complete API reference for the Neotask platform. This document covers every available endpoint, authentication methods, error handling, and rate limits.

---

## Authentication

All API requests require authentication via one of the following methods:

- **Bearer JWT**: Pass the header `Authorization: Bearer <token>`. Tokens are obtained from the login endpoints described below.
- **License HMAC**: Device-bound HMAC-SHA256 signing used by the Neotask desktop application. The client signs requests with a secret derived from the license key and device fingerprint.
- **Tenant Header**: Include `x-tenant-id: <tenantId>` for any tenant-scoped endpoint. This header identifies which tenant (workspace) the request applies to.

Many endpoints combine multiple authentication requirements. For example, "Tenant + Admin" means the request must include both a valid JWT (belonging to a user with the Admin role) and the `x-tenant-id` header.

---

## Auth Endpoints

Endpoints for user authentication across web, iOS, and desktop platforms.

| Method | Endpoint | Description | Auth |
|--------|----------|-------------|------|
| POST | `/api/auth/login` | Authenticate with email and password. Returns a JWT on success. | None |
| POST | `/api/auth/google` | Authenticate via Google OAuth on the web. Expects a Google authorization code. | None |
| POST | `/api/auth/google-ios` | Authenticate via Google OAuth on iOS. Expects an iOS-specific authorization payload. | None |
| POST | `/api/auth/google-token` | Verify a Google access token and return an Neotask JWT. | None |
| GET | `/api/auth/apple/start/` | Start the web Sign in with Apple redirect flow. Accepts `mode=signin\|onboarding` and optional `next`. | None |
| POST | `/api/auth/apple/callback` | Sign in with Apple form-post callback. Exchanges the authorization code and creates a short-lived result ticket. | None |
| POST | `/api/auth/apple/result/` | Consumes a short-lived Apple result ticket and returns the Neotask JWT/session payload. | None |
| POST | `/api/auth/apple/notifications` | Apple server-to-server notification receiver for email relay and consent/account changes. | Apple JWS |
| POST | `/api/auth/apple` | Direct-token Apple Sign-In compatibility endpoint. Expects an Apple identity token. | None |
| GET | `/api/auth/me` | Return the authenticated user's profile (name, email, avatar, roles). | JWT |
| DELETE | `/api/auth/account` | Permanently delete the authenticated user's account and all associated data. | JWT |

---

## Dashboard Auth Endpoints

Authentication endpoints specific to the Neotask dashboard, including license-key login and two-factor authentication (TOTP).

| Method | Endpoint | Description | Auth |
|--------|----------|-------------|------|
| POST | `/api/dashboard/auth/login` | Authenticate with a license key. Returns a JWT on success, or signals that TOTP is required. | None |
| POST | `/api/dashboard/auth/totp-login` | Complete login with the purchaser email plus a TOTP code or backup code when two-factor authentication is enabled. | None |
| GET | `/api/dashboard/auth/me` | Return the current license information and feature entitlements for the authenticated dashboard user. | JWT |
| POST | `/api/dashboard/totp/setup` | Generate a TOTP secret and QR code for setting up two-factor authentication. | JWT |
| POST | `/api/dashboard/totp/verify` | Verify a TOTP code to confirm and enable two-factor authentication on the account. | JWT |
| POST | `/api/dashboard/totp/recovery-codes/regenerate` | Replace all recovery codes with eight one-time v2 codes after confirming a live TOTP code. | JWT |

---

## Billing Endpoints

Manage subscriptions, checkout sessions, and in-app purchases through Stripe and RevenueCat.

| Method | Endpoint | Description | Auth |
|--------|----------|-------------|------|
| POST | `/api/billing/checkout` | Create a Stripe Checkout session for the Pro plan. Returns a checkout URL. | Tenant + Admin |
| POST | `/api/billing/checkout/enterprise` | Create a Stripe Checkout session for the Enterprise plan. Returns a checkout URL. | Tenant + Admin |
| GET | `/api/billing/status` | Return the current plan, message count, and usage limits for the tenant. | Tenant + Viewer |
| POST | `/api/billing/portal` | Create a Stripe Customer Portal session for managing payment methods and invoices. | Tenant + Admin |
| POST | `/api/billing/agent-addon` | Purchase an additional agent slot add-on for the tenant. | Tenant + Admin |
| POST | `/api/billing/webhook` | Stripe webhook handler. Validates the Stripe signature and processes subscription lifecycle events. | Stripe Signature |
| POST | `/api/billing/revenuecat-sync` | Verify an iOS in-app purchase via RevenueCat and sync entitlements to the tenant. | Tenant + Admin |
| POST | `/api/billing/revenuecat-webhook` | RevenueCat webhook handler. Processes subscription events originating from the App Store. | Bearer |

---

## Chat Endpoints

Send and receive messages, manage sessions, and poll for asynchronous job results.

| Method | Endpoint | Description | Auth |
|--------|----------|-------------|------|
| POST | `/api/chat/init` | Auto-provision a tenant, agent, and session for the authenticated user. Use this to bootstrap a new user's chat environment in a single call. | JWT |
| POST | `/api/chat/send` | Send a message to the agent. The message is processed asynchronously; a job ID is returned immediately. | Tenant + Admin |
| GET | `/api/chat/jobs/:jobId` | Poll the status and result of an asynchronous chat job by its ID. | Tenant + Viewer |
| GET | `/api/chat/messages` | Fetch all messages for a given session. Pass the session ID as a query parameter. | Tenant + Viewer |
| GET | `/api/chat/sessions` | List all chat sessions for the tenant. | Tenant + Viewer |
| POST | `/api/chat/sessions` | Create a new chat session. | Tenant + Admin |

Every `POST /api/chat/send` caller must send an `Idempotency-Key` header containing 8-200 printable ASCII characters without spaces and reuse that exact key when retrying the same turn. A missing key returns `428 IDEMPOTENCY_KEY_REQUIRED`; reusing a key with different session, company scope, message, or attachments returns `409 IDEMPOTENCY_KEY_REUSED`. A retry of an accepted request returns the original `202` job and user-message identity with `Idempotency-Replayed: true`.

---

## Agent and Activity Endpoints

Browse agents, sessions, tools, files, skills, channels, scheduled jobs, and teams associated with the tenant.

| Method | Endpoint | Description | Auth |
|--------|----------|-------------|------|
| GET | `/api/activity/agents` | List all agents belonging to the tenant. | Tenant |
| GET | `/api/activity/sessions` | List sessions. Supports filtering by `agentId`, `status`, and date range query parameters. | Tenant |
| GET | `/api/activity/sessions/:id/entries` | Get all entries (messages and events) for a specific session. | Tenant |
| GET | `/api/activity/tools` | List all tools available to the tenant's agents. | Tenant |
| GET | `/api/activity/files` | List all files associated with the tenant's agents. | Tenant |
| GET | `/api/activity/skills` | List all skills associated with the tenant's agents. | Tenant |
| GET | `/api/activity/channels` | List all channels associated with the tenant's agents. | Tenant |
| GET | `/api/activity/cron-jobs` | List all scheduled (cron) jobs for the tenant. | Tenant |
| GET | `/api/activity/teams` | List all teams within the tenant. | Tenant |

---

## Skills Endpoints

Manage the skill catalog, install and configure skills, and publish custom
skills. The legacy metadata-only custom registration endpoints are retired;
use the [durable custom skills and plugins flow](neotask-desktop/custom-skills-and-plugins.md)
so Neotask can verify source bytes and bind the intended target.

| Method | Endpoint | Description | Auth |
|--------|----------|-------------|------|
| GET | `/api/skills/catalog` | Browse the full skill catalog. Returns all published skills available for installation. | Tenant |
| GET | `/api/skills/list` | List the skills currently installed by the user. | Tenant + Viewer |
| POST | `/api/skills/sync` | Sync skills from the filesystem. Use this after deploying new skill files to refresh the registry. | Tenant + Admin |
| POST | `/api/skills/register` | Retired. Returns `410 legacy_skill_registration_retired`; use Create Skill or a supported desktop import. | Tenant + Admin |
| DELETE | `/api/skills/register/:skillId` | Retired. Returns `410 legacy_skill_registration_retired` and preserves legacy metadata for audit and explicit re-import. | Tenant + Admin |
| POST | `/api/skills/:skillId/publish` | Publish a skill to make it available in the catalog. | Tenant + Admin |
| POST | `/api/skills/:skillId/unpublish` | Unpublish a skill, removing it from the catalog. | Tenant + Admin |
| GET | `/api/skills/all` | List all skills including unpublished ones. Admin-only endpoint for skill management. | Tenant + Admin |
| PUT | `/api/skills/:skillId/env-schema` | Define or update the environment variable schema for a skill. This controls which configuration fields are presented to users. | Tenant + Admin |
| POST | `/api/skills/:skillId/configure` | Save configuration values for an installed skill. | Tenant + Viewer |
| DELETE | `/api/skills/:skillId/configure` | Remove all configuration for a skill, resetting it to defaults. | Tenant + Viewer |

---

## Channel Endpoints

Link, configure, enable, and disconnect messaging channels (e.g., Slack, Discord, WhatsApp).

| Method | Endpoint | Description | Auth |
|--------|----------|-------------|------|
| GET | `/api/channels/` | List all channels and their current statuses. | Tenant + Viewer |
| GET | `/api/channels/:channel/status` | Get the detailed status of a specific channel. | Tenant + Viewer |
| POST | `/api/channels/:channel/link` | Start the linking process for a channel. Returns a link URL or session token depending on the channel type. | Tenant + Admin |
| GET | `/api/channels/:channel/link/wait` | Long-poll for the completion of a channel linking flow. Returns once the channel is successfully linked or the operation times out. | Tenant + Admin |
| GET | `/api/channels/:channel/jobs/:jobId` | Get the result of a channel-specific asynchronous job. | Tenant + Admin |
| POST | `/api/channels/:channel/enable` | Enable a linked channel so the agent begins receiving messages from it. | Tenant + Admin |
| POST | `/api/channels/:channel/disable` | Disable a channel without unlinking it. The agent stops receiving messages but the channel connection is preserved. | Tenant + Admin |
| POST | `/api/channels/:channel/disconnect` | Fully disconnect and unlink a channel. | Tenant + Admin |
| GET | `/api/channels/:channel/config` | Get the current configuration for a channel. | Tenant + Admin |
| POST | `/api/channels/:channel/config` | Update the configuration for a channel. | Tenant + Admin |

---

## Google OAuth Endpoints

Initiate and manage Google OAuth flows for connecting Google services to Neotask.

| Method | Endpoint | Description | Auth |
|--------|----------|-------------|------|
| GET/POST | `/oauth/google/start` | Initiate a Google OAuth flow. Accepts optional parameters to specify which Google services to request access to. | Optional |
| GET | `/oauth/google/services` | List all Google service definitions supported by Neotask, grouped by category. | None |
| GET | `/oauth/google/callback` | OAuth callback handler. Google redirects here after the user grants or denies access. | None |
| GET | `/oauth/google/status` | Poll the status of an in-progress OAuth flow. Returns whether the flow is pending, completed, or failed. | None |

### Available Google Services

Neotask supports connecting to 25 Google services, organized by category:

| Category | Services |
|----------|----------|
| **Core** | Gmail, Calendar, Drive, Docs, Sheets, Slides, Forms, Keep, Tasks |
| **Communication** | People/Contacts, Chat, Meet, YouTube, Photos |
| **Location** | Places API, Routes/Directions, Business Profile |
| **Specialized** | Classroom, Play Developer, AdSense, Google Ads |

---

## Provider Keys Endpoints

Manage third-party API keys (e.g., for LLM providers). Keys are encrypted at rest and can be resolved (decrypted) on demand.

| Method | Endpoint | Description | Auth |
|--------|----------|-------------|------|
| PUT | `/api/provider-keys/:provider` | Save or update an API key for the specified provider. The key is encrypted before storage. | HMAC + Auth |
| GET | `/api/provider-keys/` | List all saved provider keys. Key values are masked (only the last four characters are shown). | Auth |
| DELETE | `/api/provider-keys/:provider` | Remove a saved API key for the specified provider. | HMAC + Auth |
| GET | `/api/provider-keys/:provider/resolve` | Decrypt and return the full API key for the specified provider. | Auth |
| GET | `/api/provider-keys/mode` | Get the current key mode (user-provided vs. platform credits) and the remaining credit balance. | Auth |

### Allowed Providers

The `:provider` path parameter must be one of the following values:

- `anthropic`
- `openai`
- `openai-codex`
- `openrouter`
- `google-ai`

---

## Usage Endpoints

Track usage, query analytics, monitor spending, and manage budgets.

| Method | Endpoint | Description | Auth |
|--------|----------|-------------|------|
| POST | `/api/usage/ingest` | Ingest a usage data record (e.g., token counts, model used). | Auth |
| GET | `/api/usage/query` | Query usage analytics with flexible filters (date range, model, agent). | Auth |
| GET | `/api/usage/summary` | Get a usage summary for a given period. Pass `period` as a query parameter (e.g., `day`, `week`, `month`). | Auth |
| GET | `/api/usage/analytics` | Retrieve detailed usage analytics including breakdowns by model and agent. | Auth |
| GET | `/api/usage/spending` | Get spending data for a given period. Pass `period` as a query parameter. | Auth |
| GET | `/api/usage/budget` | Get budget information including the total limit, amount used, and amount remaining. | Auth |
| POST | `/api/usage/cron-runs` | Record the execution of a scheduled (cron) job for usage tracking. | Auth |
| POST | `/api/usage/budget-snapshot` | Capture a point-in-time snapshot of the current budget state. | Auth |

---

## Onboarding Endpoints

Guide new users through initial setup, including selecting a model provider and configuring an API key.

| Method | Endpoint | Description | Auth |
|--------|----------|-------------|------|
| POST | `/api/onboarding/init` | Initialize the onboarding configuration for the authenticated user. Creates default settings and returns the onboarding state. | JWT |
| GET | `/api/onboarding/models` | List available model providers and their supported models. This endpoint is public and does not require authentication. | None |
| POST | `/api/onboarding/setup` | Configure a provider API key during onboarding. Validates the key before saving. | Tenant + Admin |
| POST | `/api/onboarding/complete` | Mark onboarding as complete for the current user. | Dashboard Auth |

---

## Tenant Endpoints

Create and manage tenants (workspaces), store encrypted secrets, and create sessions and jobs directly.

| Method | Endpoint | Description | Auth |
|--------|----------|-------------|------|
| POST | `/api/tenants/` | Create a new tenant (workspace). Returns the tenant ID and default settings. | JWT |
| GET | `/api/tenants/:tenantId` | Get details for a specific tenant, including settings and member count. | JWT |
| POST | `/api/tenants/secrets` | Store an encrypted secret associated with the tenant. Used for service integrations. | Tenant + Admin |
| POST | `/api/tenants/sessions` | Create a new session within the tenant. | Tenant + Admin |
| POST | `/api/tenants/jobs` | Create a new asynchronous job within the tenant. | Tenant + Admin |

---

## Memory Endpoints

Manage agent memory configuration, files, and content. Memory allows agents to persist information across sessions.

| Method | Endpoint | Description | Auth |
|--------|----------|-------------|------|
| GET | `/api/memory/config` | Fetch the current memory configuration (enabled state, retention policy, limits). | Auth |
| POST | `/api/memory/config` | Update memory settings such as retention period and storage limits. | Auth |
| GET | `/api/memory/files` | List all memory files stored for the agent. | Auth |
| GET | `/api/memory/files/:filename` | Retrieve the contents of a specific memory file by filename. | Auth |
| DELETE | `/api/memory/files/:filename` | Delete a specific memory file by filename. | Auth |
| GET | `/api/memory/content` | Retrieve stored memory content. | Auth |
| POST | `/api/memory/content` | Store new memory content for the agent. | Auth |

---

## Google Accounts Endpoints

Manage Google accounts that have been connected to Neotask via OAuth.

| Method | Endpoint | Description | Auth |
|--------|----------|-------------|------|
| GET | `/api/google-accounts/` | List all connected Google accounts with their service scopes and status. | Auth |
| POST | `/api/google-accounts/:accountId/activate` | Activate a connected Google account, enabling the agent to use its authorized services. | Auth |
| DELETE | `/api/google-accounts/:accountId` | Remove a connected Google account and revoke its stored tokens. | Auth |

---

## Contact and Support Endpoints

Submit and manage support contact requests.

| Method | Endpoint | Description | Auth |
|--------|----------|-------------|------|
| POST | `/api/contact/` | Submit a contact form message. Rate limited to 5 requests per 15 minutes per IP address. | None |
| GET | `/api/contacts/` | List all contact submissions with pagination support. Admin-only. | Admin |
| PATCH | `/api/contacts/:id` | Update the status of a contact submission (e.g., mark as resolved). | Admin |
| DELETE | `/api/contacts/:id` | Delete a contact submission. | Admin |

---

## Rate Limits

Neotask enforces rate limits on certain endpoints to protect service stability. When a rate limit is exceeded, the API returns a `429 Too Many Requests` response.

| Endpoint Category | Limit |
|-------------------|-------|
| Contact form | 5 requests per 15 minutes per IP |
| Login attempts | 10 requests per 15 minutes per IP |
| Tracking/analytics | 30 requests per 60 seconds per IP |

---

## Error Responses

All error responses follow a consistent JSON format:

```json
{
  "error": "Error message description",
  "status": 400
}
```

### Status Codes

| Code | Meaning |
|------|---------|
| 400 | **Bad Request** -- The request was malformed or contained invalid parameters. |
| 401 | **Unauthorized** -- Authentication is missing or the provided token is invalid. |
| 402 | **Payment Required** -- The tenant's credits have been depleted. Upgrade your plan or add credits to continue. |
| 403 | **Forbidden** -- The authenticated user does not have sufficient permissions for this action. |
| 404 | **Not Found** -- The requested resource does not exist. |
| 429 | **Rate Limited** -- Too many requests. Wait and retry after the period indicated in the response headers. |
| 500 | **Internal Server Error** -- An unexpected error occurred on the server. If this persists, contact Neotask support. |