> For the complete documentation index, see [llms.txt](https://runtimedesigns.gitbook.io/token-buzz/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://runtimedesigns.gitbook.io/token-buzz/developers-api/overview.md).

# Developer / API Overview

TokenBuzz exposes two distinct API surfaces — a hosted, Clerk-authenticated set of Next.js route handlers, and a separate Spring Boot ingestion/analytics service (`api-caller`) with its own authentication contract.

## The two API surfaces

### 1. Hosted app routes (Next.js, Clerk auth)

These are the routes served by the TokenBuzz application at `app.tokenbuzz.app`. Every request must carry a valid Clerk session cookie or bearer token — unauthenticated requests receive `401 Unauthorized`.

| Base path              | Purpose                                                          |
| ---------------------- | ---------------------------------------------------------------- |
| `POST /api/query`      | Trigger multi-source social ingestion and return ingestion stats |
| `GET /api/query/quota` | Return the caller's current ingestion quota status               |
| `GET /api/analytics/*` | Query pre-aggregated analytics stored in DynamoDB                |

These routes are documented in [Query API](/token-buzz/developers-api/query-api.md) and [Analytics API](/token-buzz/developers-api/analytics-api.md).

**Important:** The hosted app routes do **not** use Auth0 JWTs or an `X-Internal-API-Key` header. Those authentication mechanisms belong exclusively to the `api-caller` service described below.

### 2. api-caller service (Spring Boot, Auth0 / internal key auth)

`api-caller` is a Spring Boot (Java 21) ingestion and analytics service that backs the platform. It:

* Ingests tweets and posts from the external `twitterapi.io` API into PostgreSQL.
* Exposes analytics endpoints over stored tweets and authors.
* Exposes read-only raw-table endpoints (`/api/data/*`) for BI and debugging.
* Optionally dispatches tweets to `api-ai` for asynchronous sentiment analysis.

In Traefik deployments, the service is reachable under the `/caller` path prefix:

```
POST   /caller/api/query
GET    /caller/api/query
POST   /caller/api/tweets/by-ids
GET    /caller/api/analytics/<endpoint>
GET    /caller/api/symbols/rate
GET    /caller/api/data/<table>
```

Authentication for this service uses Auth0 JWT bearer tokens or an `X-Internal-API-Key` header — see [Authentication](/token-buzz/developers-api/authentication.md) for details.

## Content types

All endpoints accept and return `application/json` unless stated otherwise. Requests with a body must set `Content-Type: application/json`.

## Base URLs

| Surface                 | Base URL                                        |
| ----------------------- | ----------------------------------------------- |
| Hosted app (production) | `https://app.tokenbuzz.app`                     |
| Hosted app (PR preview) | `https://pr-<N>.staging.tokenbuzz.app`          |
| api-caller service      | Deployment-specific; contact your administrator |

## Authentication

See [Authentication](/token-buzz/developers-api/authentication.md) for full details on both authentication mechanisms.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://runtimedesigns.gitbook.io/token-buzz/developers-api/overview.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.