Reference

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: Namespace management.
• /v1/namespaces/{namespaceId}/managers: Manager configuration & status.
• /v1/namespaces/{namespaceId}/connections: Webhook and notification channel integrations.
• /v1/namespaces/{namespaceId}/managers/{managerId}/scans: Retrieve Scans.

Standard API Conventions

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

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.

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).

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"

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

Test Mode

You can execute API requests in a simulated "test" mode by including the x-test HTTP header in your request. This is useful for verifying configurations, testing integrations, or simulating actions without creating persistent side effects.

• Header: x-test
• Supported Values: true, yes to enable (case-insensitive); false, no to disable.

When test mode is enabled, the request is flagged and processed within a test context.

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.