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:

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 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:

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:

{
  "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.