> ## Documentation Index
> Fetch the complete documentation index at: https://agnt.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Request Format

> Learn how to structure API requests to agntdata.

## Base URL

All API requests are made to:

```
https://api.agntdata.dev/v1
```

## Authentication

Include your API key in the `Authorization` header:

```bash theme={null}
Authorization: Bearer YOUR_API_KEY
```

## Request Structure

### GET Requests

Most data retrieval endpoints use GET requests with query parameters:

```bash theme={null}
GET /v1/{platform}/{operation}?param1=value1&param2=value2
```

Example:

```bash theme={null}
curl -X GET "https://api.agntdata.dev/v1/data/linkedin/get-company-details?username=microsoft" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

### POST Requests

Some endpoints accept POST requests with JSON bodies for complex queries:

```bash theme={null}
POST /v1/{platform}/{operation}
Content-Type: application/json

{
  "param1": "value1",
  "param2": "value2"
}
```

## Common Parameters

### Identifiers

Most endpoints accept one or more identifier parameters:

| Parameter  | Description              | Example                                  |
| ---------- | ------------------------ | ---------------------------------------- |
| `username` | Public username/handle   | `microsoft`, `@mkbhd`                    |
| `id`       | Platform-specific ID     | `123456789`                              |
| `url`      | Full profile/content URL | `https://linkedin.com/company/microsoft` |

<Note>
  The available identifiers vary by platform and endpoint. Check the API reference for each endpoint's supported parameters.
</Note>

### Pagination

For list endpoints, use pagination parameters:

| Parameter | Description                              | Default |
| --------- | ---------------------------------------- | ------- |
| `limit`   | Number of results to return              | 20      |
| `cursor`  | Pagination cursor from previous response | —       |

### Filtering

Some endpoints support filtering:

| Parameter | Description                                |
| --------- | ------------------------------------------ |
| `since`   | Return results after this date (ISO 8601)  |
| `until`   | Return results before this date (ISO 8601) |
| `sort`    | Sort order (`recent`, `popular`, etc.)     |

## Request Examples

### LinkedIn Company Details

```bash theme={null}
curl -X GET "https://api.agntdata.dev/v1/data/linkedin/get-company-details?username=microsoft" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

### YouTube Channel Videos

```bash theme={null}
curl -X GET "https://api.agntdata.dev/v1/data/youtube/get-channel-videos?username=@mkbhd&limit=10" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

### X User Search

```bash theme={null}
curl -X GET "https://api.agntdata.dev/v1/data/x/search-users?query=ai+researcher&limit=20" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

### With Pagination

```bash theme={null}
# First page
curl -X GET "https://api.agntdata.dev/v1/data/linkedin/get-company-posts?username=microsoft&limit=20" \
  -H "Authorization: Bearer YOUR_API_KEY"

# Next page (using cursor from previous response)
curl -X GET "https://api.agntdata.dev/v1/data/linkedin/get-company-posts?username=microsoft&limit=20&cursor=abc123" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

## Response Structure

### Successful Response

```json theme={null}
{
  "success": true,
  "data": {
    "id": "1035",
    "name": "Microsoft",
    "username": "microsoft",
    "description": "We're on a mission to empower...",
    "website": "https://microsoft.com",
    "followerCount": 22000000,
    "employeeCount": 228000
  },
  "meta": {
    "costCents": 1,
    "purchasedBalanceCents": 949,
    "subscriptionRemainingCents": 500,
    "cached": false,
    "latencyMs": 245
  }
}
```

### List Response

```json theme={null}
{
  "success": true,
  "data": [
    { "id": "1", "title": "Post 1" },
    { "id": "2", "title": "Post 2" }
  ],
  "meta": {
    "costCents": 5,
    "purchasedBalanceCents": 944,
    "subscriptionRemainingCents": 500,
    "cached": false,
    "latencyMs": 312
  }
}
```

### Error Response

```json theme={null}
{
  "success": false,
  "error": {
    "code": "NOT_FOUND",
    "message": "Company not found with username: nonexistent"
  }
}
```

## Headers

### Request Headers

| Header          | Required | Description                    |
| --------------- | -------- | ------------------------------ |
| `Authorization` | Yes      | Bearer token with your API key |
| `Content-Type`  | For POST | `application/json`             |

### Response Headers

| Header        | Description                                      |
| ------------- | ------------------------------------------------ |
| `Retry-After` | Seconds to wait (only present when rate limited) |

## SDK Examples

### JavaScript/TypeScript

```typescript theme={null}
const response = await fetch(
  'https://api.agntdata.dev/v1/data/linkedin/get-company-details?username=microsoft',
  {
    headers: {
      'Authorization': `Bearer ${process.env.AGNTDATA_API_KEY}`
    }
  }
);

const { success, data, error } = await response.json();

if (!success) {
  throw new Error(error.message);
}

console.log(data.name); // "Microsoft"
```

### Python

Use `httpx` or `requests` with a Bearer token:

```python theme={null}
import os
import httpx

response = httpx.get(
    "https://api.agntdata.dev/v1/data/linkedin/get-company-details",
    params={"username": "microsoft"},
    headers={"Authorization": f"Bearer {os.environ['AGNTDATA_API_KEY']}"},
)
data = response.json()
if not data["success"]:
    raise RuntimeError(data["error"]["message"])
print(data["data"]["name"])
```

## Next Steps

<CardGroup cols={2}>
  <Card title="Pagination" icon="list" href="/data-apis/pagination">
    Learn how to handle paginated responses.
  </Card>

  <Card title="Error Handling" icon="triangle-exclamation" href="/concepts/errors">
    Handle errors gracefully.
  </Card>
</CardGroup>