Getting Started

A step-by-step guide to querying the Advite API.

Introduction

This guide will walk you through the core workflow of the Advite API. We'll go from a clean slate to pulling matched posts using your API key.

The Core Workflow

  1. Create a Workspace (Namespace): The logical container for your monitors and connections.
  2. Create a Monitor (Manager): An AI-powered monitor that watches platforms (like Reddit) for relevant posts.
  3. Retrieve Matches (Scans): Pulling matches via polling, or receiving them via your webhook.

Authentication

All API requests must include your API key in the Authorization header as a Bearer token:

Authorization: Bearer YOUR_API_KEY

You can reach out to our team to get setup with an API key.

Step 1: Create a Workspace (Namespace)

Workspaces (referred to as Namespaces in the API) are the parent resources for everything you create. Let's create your first Workspace.

Request

curl -X POST https://api.advite.ai/v1/namespaces \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "nickname": "My First Workspace"
  }'

Response

{
  "name": "namespaces/abc123xyz",
  "createTime": "2026-06-13T12:00:00Z",
  "updateTime": "2026-06-13T12:00:00Z",
  "nickname": "My First Workspace",
  "metadata": {}
}

Make note of the name property in the response (e.g., namespaces/abc123xyz). The portion after namespaces/ is your namespaceId (e.g., abc123xyz), which you'll use in subsequent requests.

Step 2: Create a Monitor (Manager)

Now, let's create an AI-powered Monitor (referred to as a Manager in the API).

To keep things simple, you don't need to write complex instructions. By using the input property, you can specify your target seed URLs and focus strategy (e.g., SALES, COMPETITOR, CRISIS), and Advite's backend will automatically generate the actual instructions for the AI monitor.

Request

Substitute {namespaceId} with your ID from Step 1:

curl -X POST https://api.advite.ai/v1/namespaces/{namespaceId}/managers \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "nickname": "My Reddit Monitor",
    "type": "FEED_MANAGER",
    "enable": true,
    "source": {
      "type": "REDDIT"
    },
    "input": {
      "type": "STRUCTURED",
      "urls": [
        "https://mycompany.com"
      ],
      "focus": {
        "type": "SALES"
      }
    }
  }'

Response

{
  "name": "namespaces/abc123xyz/managers/mgr789",
  "nickname": "My Reddit Monitor",
  "type": "FEED_MANAGER",
  "enable": true,
  "mode": "AUTOMATIC",
  "state": "PENDING_APPLY",
  "source": {
    "type": "REDDIT"
  },
  "input": {
    "type": "STRUCTURED",
    "urls": ["https://mycompany.com"],
    "focus": {
      "type": "SALES"
    }
  }
}

Background Processing Note

Important: Notice that the state in the response is "PENDING_APPLY". Because you used the input property, Advite's backend processes your URLs and focus strategy in the background to automatically compile the final Monitor.

Step 3: Pulling Matches (Scans)

To fetch matches identified by your monitor, you can poll for matched posts manually. These matched posts are referred to as Scans in the API.

Request

Substitute {namespaceId} and {managerId} (e.g., mgr789 from the previous step):

curl -X GET https://api.advite.ai/v1/namespaces/{namespaceId}/managers/{managerId}/scans \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

{
  "scans": [
    {
      "name": "namespaces/abc123xyz/managers/mgr789/scans/scan999",
      "createTime": "2026-06-13T12:15:00Z",
      "post": {
        "type": "REDDIT_LINK",
        "time": "2026-06-13T12:10:00Z",
        "id": "t3_123456",
        "title": "Looking for recommendations for social-monitoring tools",
        "text": "My company is growing and we need to monitor brand mentions and potential leads on social media. Are there any good automated platforms out there?",
        "url": "https://reddit.com/r/marketing/comments/123456/recs_needed",
        "subreddit": {
          "id": "t5_2qi1r",
          "name": "marketing",
          "url": "https://reddit.com/r/marketing"
        },
        "user": {
          "id": "t2_abc123",
          "name": "marketing_pro",
          "url": "https://reddit.com/user/marketing_pro"
        }
      },
      "feedback": []
    }
  ],
  "nextPageToken": ""
}

Next Steps

Now that you have successfully set up your workspace, created a monitor, and fetched matches, check out:

Introduction

What can I do with the API?

API Reference & Glossary

An overview of the Advite OpenAPI specification, standard API conventions, terminology, and error handling.

advite © 2026