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

# API Structure

## Request Structure

All Falcon queries are sent using a **POST request** with a JSON body.

```
POST /query
Content-Type: application/json
```

Each request includes an `agent_id` which determines the dataset being queried, along with optional parameters for filtering, pagination, and formatting.

### Request Body Schema

Every Falcon API request follows the structure below.

```json
{
  "agent_id": number,
  "params": { ... },
  "pagination": {
    "limit": number,
    "offset": number
  },
  "formatter_config": {
    "format_type": string
  }
}
```

### Request Fields

#### agent\_id

**Required**

Identifies the dataset or endpoint logic being queried.

Each Falcon dataset is mapped to a specific `agent_id`.

Example:

```json
"agent_id": 555
```

#### params

**Optional**

Contains dataset-specific filters for the request.

Common examples include:

* market status
* market slug
* timestamps
* trader addresses
* token identifiers

Example:

```json
"params": {
  "closed": "false",
  "market_slug": "bitcoin"
}
```

#### pagination

**Optional**

Controls the number of records returned and the result offset.

Fields:

* **limit** — maximum number of records returned
* **offset** — starting index for the query

Example:

```json
"pagination": {
  "limit": 10,
  "offset": 0
}
```

#### formatter\_config

**Optional**

Controls how the response data is formatted.

Example:

```json
"formatter_config": {
  "format_type": "raw"
}
```

### Example Request

```json
{
  "agent_id": 555,
  "params": {
    "closed": "false",
    "market_slug": "bitcoin"
  },
  "pagination": {
    "limit": 10,
    "offset": 0
  },
  "formatter_config": {
    "format_type": "raw"
  }
}
```

***

## Response Structure

Falcon responses follow a consistent schema across all datasets. This ensures predictable data handling when integrating the API.

### Response Schema

```json
{
  "timestamp": "ISO timestamp",
  "params": { ... },
  "pagination": {
    "limit": number,
    "offset": number,
    "has_more": boolean
  },
  "data": {
    "results": [ ... ]
  }
}
```

### Response Fields

#### timestamp

The server timestamp indicating when the response was generated.

Example:

```json
"timestamp": "2025-01-09T19:12:50Z"
```

#### params

Echoes the parameters used for the query. This helps verify the request configuration in the response.

#### pagination

Contains metadata about the returned dataset.

Fields:

* **limit** — number of records returned
* **offset** — starting index of the dataset
* **has\_more** — indicates whether more records are available

#### data.results

An array containing the returned dataset records.

The structure of each object depends on the specific Falcon dataset being queried.

### Example Response

```json
{
  "timestamp": "2025-01-09T19:12:50Z",
  "params": {},
  "pagination": {
    "limit": 10,
    "offset": 0,
    "has_more": true
  },
  "data": {
    "results": []
  }
}
```

***

## Tips for Best Results

* Always include `pagination.limit` to avoid unnecessarily large responses.
* Use `params` filters whenever possible to narrow the dataset.
* Check `pagination.has_more` to determine if additional requests are needed.
* Store the `offset` value to paginate through large datasets.