API Reference & Glossary

OpenAPI Reference Overview

The entire Advite API is documented interactively using the OpenAPI 3.0 standard. You can explore, test endpoints, and generate client libraries directly from our interactive documentation portal:

Advite Interactive API Reference

Spec Layout & Resource Paths

Our endpoints are organized around RESTful resources grouped under /v1/. For example, all resources exist in a hierarchical tree rooted in your Workspace (Namespace):

• /v1/namespaces: Workspace management.
• /v1/namespaces/{namespaceId}/managers: Monitor configuration & status.
• /v1/namespaces/{namespaceId}/connections: Webhook and notification channel integrations.
• /v1/namespaces/{namespaceId}/managers/{managerId}/scans: Retrieve matched posts.

Glossary & Synonyms

When integrating with the API, you may encounter different names for the same core concepts depending on whether you are reading the API schema or using the Advite Dashboard.

Below is a breakdown of the terminology and their synonyms:

Workspace / Namespace

• Console Term: Workspace
• API Resource Name: Namespace (e.g., namespaces/{namespaceId})
• Description: The top-level logical container for all your resources, billing details, and team members. Every API resource you create must belong to a Namespace.

Monitor / Manager

• Console Term: Monitor
• API Resource Name: Manager or Feed Manager (e.g., namespaces/{namespaceId}/managers/{managerId})
• Description: The AI agent configured to scan platforms for relevant activity based on a simplified goal and seed URLs.

Match / Alert / Scan

• Console Term: Match or Alert
• API Resource Name: Scan (e.g., namespaces/{namespaceId}/managers/{managerId}/scans/{scanId})
• Description: A specific post or piece of content identified and extracted by your Monitor as matching your target criteria.

Webhook / Integration / Connection

• Console Term: Connection
• API Resource Name: Connection (e.g., namespaces/{namespaceId}/connections/{connectionId})
• Description: An external communication integration. This includes raw HTTP endpoints (Webhooks), Slack Channels, or email digests.

Feed / Source Stream

• Console Term: Managed by the Monitor
• API Resource Name: Feed (e.g., namespaces/{namespaceId}/feeds/{feedId})
• Description: The underlying raw content stream. This represents the specific query or scraper configured on a social platform (like a list of subreddits or keyword searches). While you can manage Feeds manually, your Monitor (Manager) typically creates and configures Feeds automatically behind the scenes.

Genius / AI Prompt Config

• Console Term: Managed by the Monitor
• API Resource Name: Genius (e.g., namespaces/{namespaceId}/geniuses/{geniusId})
• Description: The underlying AI model and prompt instruction engine. It translates high-level monitor rules and targets into an operational Feed. Much like Feeds, Geniuses are created and managed automatically by your Monitor (Manager), requiring no manual developer interaction.

Standard API Conventions

To ensure ease of integration, the Advite API adheres to several consistent patterns across all endpoints:

1. Resource Names

Resources are identified by unique, hierarchical strings in the name property. Instead of a simple database integer, resource IDs are returned in a relative path format:

• Example Namespace: namespaces/workspace_abc123
• Example Connection: namespaces/workspace_abc123/connections/webhook_xyz987

When making nested requests, extract the relevant segment (e.g., workspace_abc123) to use as path parameters.

2. Pagination

All list endpoints support cursor-based pagination. If a list result exceeds the page size:

1. The response will include a nextPageToken string.
2. Pass this token in your subsequent list request using the pageToken query parameter.
3. You can configure the page size limit using the pageSize query parameter (defaults to 5, maximum of 100).

3. Query Filters

List requests can be narrowed down using the filter query parameter. Filters must be formatted in Conjunctive Normal Form (CNF) like so:

GET /v1/namespaces/{namespaceId}/managers/{managerId}/scans?filter=createTime > "2026-06-13T00:00:00Z"

4. Ordering

Sort results using the orderBy query parameter, formatting as a comma-delimited list of properties and their direction:

GET /v1/namespaces/{namespaceId}/managers/{managerId}/scans?orderBy=createTime desc

5. Errors

All error responses returned by the Advite API adhere to a standard structure. If an API request fails, you will receive a non-2xx HTTP status code paired with a JSON response matching the Error schema:

{
  "code": 400,
  "message": "the nickname field must be at least 3 characters",
  "details": [
    {
      "field": "nickname",
      "issue": "too_short"
    }
  ]
}

Error Fields

• code: The corresponding HTTP status code (provided in the payload for logging convenience).
• message: A clear, lowercase, and concise description of why the operation failed.
• details: An optional array containing detailed validation issues, showing which specific fields failed and why.

HTTP Status Codes

The API utilizes standard HTTP status codes to communicate the success or failure of requests:

Rate Limits & Backoff

The API has generous rate limits to prevent abuse. If you exceed your rate limits, you will receive a 429 Too Many Requests response.

Best Practice: Exponential Backoff

When writing integration scripts, you should always handle 429 (and 5xx transient server errors) using an exponential backoff with jitter strategy. If your client receives a retryable error, wait a short period of time before retrying, doubling the wait time for each subsequent retry up to a reasonable limit.