API Reference

Complete reference for all developer-facing API endpoints on the Aiffinity Provider Platform.

On this page

Base URL
Authentication
Rate Limiting
Developer Console API
Package Management API
Provider Runtime API
Provider Capabilities API
Catalog & Install API
Response Format

Base URL

All API requests use the following base URLs:

Production: https://api.aiffinity.me
Staging: https://api.staging.aiffinity.me

All endpoints return JSON. Request bodies must be sent as application/json. All timestamps are ISO 8601 in UTC.

Authentication

The Aiffinity API uses two authentication methods depending on the surface area.

Firebase ID Token (Developer Console)

The Developer Console API, Package Management API, and Catalog API authenticate via Firebase ID tokens. Include the token in the Authorization header.

Authorization: Bearer <firebase-id-token>

Obtain a Firebase ID token by signing in via the developer console or programmatically using the Firebase Admin SDK.

OAuth 2.1 (Provider Runtime)

The Provider Runtime API and Capabilities API use OAuth 2.1 client credentials flow. Exchange your client_id and client_secret for an access token.

POST /v1/providers/auth/token
Content-Type: application/json

{
  "grant_type": "client_credentials",
  "client_id": "prov_abc123...",
  "client_secret": "secret_xyz789..."
}

// Response
{
  "access_token": "eyJhbGciOiJSUzI1NiIs...",
  "token_type": "Bearer",
  "expires_in": 3600
}

Include the access token in subsequent requests:

Authorization: Bearer <access-token>

Rate Limiting

Rate limits are enforced per-app based on your plan tier. Exceeding the limit returns 429 Too Many Requests with a Retry-After header.

Free

100 / min

For development and testing

Pro

1,000 / min

For production workloads

Enterprise

10,000 / min

Custom limits available

Rate limit headers are included in every response:

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 847
X-RateLimit-Reset: 1712246400

Developer Console API

Manage your developer account and provider apps. Requires Firebase ID token authentication.

Account

Method	Endpoint	Description
POST	/v1/providers/account	Create a new developer account. Requires `company_name`, `email`, and `password` in the request body. Returns the account object with a pending verification status.
POST	/v1/providers/account/verify	Verify your email address using the token sent to your inbox. The token expires after 24 hours.
POST	/v1/providers/account/login	Authenticate with email and password. Returns a Firebase ID token and refresh token.
GET	/v1/providers/account	Retrieve your developer account details, including company info, email, and plan tier.
PATCH	/v1/providers/account	Update account details such as company name, contact email, or notification preferences.

Apps

Method	Endpoint	Description
POST	/v1/providers/apps	Create a new provider app. Returns the app with generated `client_id` and `client_secret`. The secret is shown only once.
GET	/v1/providers/apps	List all apps belonging to your developer account. Supports `?limit` and `?offset` query parameters.
GET	/v1/providers/apps/:id	Retrieve a single app by ID, including its redirect URIs, webhook URL, and creation timestamp.
PATCH	/v1/providers/apps/:id	Update an app's name, description, redirect URIs, or webhook URL. Only provided fields are updated.
DELETE	/v1/providers/apps/:id	Delete an app. Associated packages become orphaned and are removed from the catalog after 30 days.

Package Management API

Create, version, validate, submit, and publish capability packages. Requires Firebase ID token authentication.

Method	Endpoint	Description
POST	/v1/providers/packages/manage	Create a new package with an initial version. Requires `appId`, `name`, `slug`, `description`, `riskTier`, and `capabilities` array.
GET	/v1/providers/packages/manage	List all packages for your account. Supports `?status` filter (`draft`, `published`, `deprecated`) and pagination.
GET	/v1/providers/packages/manage/:id	Retrieve a package with its full version history, install counts, and current status.
PATCH	/v1/providers/packages/manage/:id	Update package metadata (name, description, listing images). Does not affect published versions.
POST	/v1/providers/packages/manage/:id/versions	Create a new version of an existing package. Requires updated `capabilities` array and optional `changelog`.
POST	/v1/providers/packages/manage/:id/versions/:vid/validate	Run the conformance suite against a package version. Returns a score (0–100) across 6 dimensions. Minimum passing score is 80.
POST	/v1/providers/packages/manage/:id/versions/:vid/submit	Submit a version for review. `data_only` packages are automatically listed after policy checks. Higher risk tiers enter a manual review queue (typical review time: 1–3 business days).
POST	/v1/providers/packages/manage/:id/versions/:vid/publish	Publish a reviewed and approved version to the catalog. The version becomes available for installation immediately.

Provider Runtime API

Register and configure runtime apps, auth profiles, capability templates, and webhook profiles. Requires OAuth 2.1 access token authentication.

Method	Endpoint	Description
POST	/v1/providers/runtime/apps	Register a new runtime app. Binds your service endpoint to an app created via the console API.
GET	/v1/providers/runtime/apps	List all registered runtime apps for your account.
GET	/v1/providers/runtime/apps/:id	Retrieve a runtime app's configuration, including auth profile, capability template, and webhook profile.
PATCH	/v1/providers/runtime/apps/:id	Update runtime app configuration: endpoint URL, display name, or status.
PUT	/v1/providers/runtime/apps/:id/auth-profile	Upsert the authentication profile. Defines how Aiffinity authenticates with your service (OAuth 2.0, API key, or custom).
PUT	/v1/providers/runtime/apps/:id/capability-template	Upsert the capability template. Defines the schema, refresh intervals, and surface guidance for your capabilities.
PUT	/v1/providers/runtime/apps/:id/webhook-profile	Upsert the webhook profile. Configures webhook delivery: URL, events, signing secret, and retry policy.
PUT	/v1/providers/runtime/apps/:id/credential-secret	Set or rotate the credential secret used for webhook signature verification. Returns the new secret (shown once).
GET	/v1/providers/runtime/apps/:id/health	Check the runtime health of your registered app. Returns connectivity status, registered handlers, uptime, and last invocation timestamp.

Provider Capabilities API

Invoke capabilities, manage state, run sandbox tests, and monitor certification. Requires OAuth 2.1 access token authentication.

Invocation

Method	Endpoint	Description
POST	/v1/providers/capabilities/:id/invoke	Invoke a capability. Aiffinity calls this on your runtime when a user's widget needs fresh data. Payload includes user context and parameters.
GET	/v1/providers/capabilities/:id/state	Retrieve the current cached state for a capability instance. Returns the last successful invocation response and its TTL.
POST	/v1/providers/capabilities/:id/action	Execute a provider-defined action (e.g., create a task, send a message). Actions must be declared in the capability descriptor.
GET	/v1/providers/capabilities/:id/history	Retrieve invocation history for a capability. Returns the last 100 invocations with status, latency, and error details. Supports `?since` and `?limit` filters.
GET	/v1/providers/capabilities/:id/realtime	Start a Server-Sent Events (SSE) stream for real-time capability updates. The stream delivers state changes as they occur, with automatic reconnection support.

Sandbox

Method	Endpoint	Description
POST	/v1/providers/capabilities/sandbox/scenarios	Create a test scenario with mock user context, input parameters, and expected assertions. Scenarios are isolated from production data.
GET	/v1/providers/capabilities/sandbox/scenarios	List all test scenarios for your account. Supports `?capability` filter.
POST	/v1/providers/capabilities/sandbox/run	Execute a scenario against your running handler. Returns pass/fail status, assertion results, latency, and a full request/response trace.
GET	/v1/providers/capabilities/sandbox/traces	Retrieve execution traces for debugging. Includes request payload, response payload, handler duration, and any errors. Supports `?since`, `?limit`, and `?capability` filters.

Certification

Method	Endpoint	Description
GET	/v1/providers/capabilities/certification	Get the current certification status for your published packages. Returns overall score, per-dimension scores, and certification tier (`certified`, `warning`, `revoked`).
GET	/v1/providers/capabilities/baselines	Get performance baselines for your capabilities. Returns p50, p95, and p99 latency, error rate, and availability percentage over the last 30 days.
GET	/v1/providers/capabilities/alerts	List active and resolved quality alerts. Alerts are triggered when performance metrics degrade below baseline thresholds. Supports `?status` (`active`, `resolved`) and `?severity` (`info`, `warning`, `critical`) filters.

Catalog & Install API

Browse the public package catalog and manage installations. These endpoints are used by Aiffinity client apps. Requires Firebase ID token authentication.

Method	Endpoint	Description
GET	/v1/space/marketplace	Browse the package catalog. Returns published packages with listing metadata, install counts, and ratings. Supports `?q` (search), `?category`, `?sort` (`popular`, `recent`, `rating`), and pagination.
POST	/v1/space/marketplace/:id/install	Install a package for the authenticated user. Creates a capability binding and begins data sync according to the package's refresh interval.
DELETE	/v1/space/marketplace/:id/install	Uninstall a package. Removes the capability binding, stops data sync, and deletes cached state. User data held by the provider is subject to the provider's data retention policy.

Response Format

All successful responses follow a consistent envelope format:

// Success (single resource)
{
  "data": { /* resource object */ },
  "meta": {
    "requestId": "req_abc123def456"
  }
}

// Success (list)
{
  "data": [ /* array of resources */ ],
  "meta": {
    "requestId": "req_abc123def456",
    "pagination": {
      "total": 42,
      "limit": 20,
      "offset": 0,
      "hasMore": true
    }
  }
}

// Error
{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "name: String must contain at least 1 character",
    "requestId": "req_abc123def456"
  }
}

For a complete list of error codes and their meanings, see the Errors page.