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

# API Reference

> Complete reference documentation for the IntentGPT B2B Intent API

## Overview

The IntentGPT B2B Intent API provides comprehensive intent analysis, lead generation, and company intelligence capabilities for B2B companies. Our API enables you to analyze intent signals, generate leads, manage customer data, and access powerful business intelligence tools.

## Base URL

All API requests should be made to:

```bash theme={null}
https://api.intentgpt.ai
```

## Authentication

The API supports multiple authentication methods:

### API Key Authentication

Use the `X-API-Key` header:

```bash theme={null}
X-API-Key: your_api_key_here
```

### Bearer Token Authentication

Use JWT tokens from Clerk authentication or API keys:

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

<Note>
  Never share your API key or commit it to version control. New API keys are automatically generated with 5000 free credits.
</Note>

## Rate Limits

The API provides the following rate limits by endpoint:

* Intent & Analysis endpoints: Up to 1000 results per request
* Lead generation: 1000 leads maximum per request
* API key management: Standard rate limiting applied
* Health & testing endpoints: No authentication required

## API Endpoint Categories

### Intelligence Analysis

* `GET /company` - Company intelligence (GTM-optimized by default)
* `GET /company-gtm` - Explicit GTM company analysis
* `GET /person` - Person intelligence (GTM-optimized by default)
* `GET /person-gtm` - Explicit GTM person analysis

### Lead Generation

* `GET /leadgen` - Generate leads with customizable criteria
* `GET /leadgen/lists` - Retrieve lead lists
* `POST /leadgen/lists` - Create new lead lists
* `PUT /leadgen/lists/{id}` - Update existing lead lists
* `DELETE /leadgen/lists/{id}` - Delete lead lists

### Person & List Management

* `GET /person/list` - Person list management
* `GET /swipemagic` - SwipeMagic functionality

### Account Management

* `GET /api/credits` - Check user credit balance

### System & Testing

* `GET /health` - System health check
* `GET /test-auth` - Test authentication methods
* `GET /cors-test` - Test CORS configuration

## Core Intelligence Endpoints

### Company Intelligence

Get GTM-focused insights into companies with lead scoring and competitive analysis.

#### Example Request

```bash theme={null}
curl -X GET "https://api.intentgpt.ai/company?website=asana.com" \
-H "Authorization: Bearer your_api_key"
```

### Person Intelligence

Analyze individual prospects with buying signals and decision-power assessment.

#### Example Request

```bash theme={null}
curl -X GET "https://api.intentgpt.ai/person?linkedin=john-doe" \
-H "Authorization: Bearer your_api_key"
```

## Lead Generation

### GET /leadgen

Generate leads based on specified criteria.

#### Example Request

```bash theme={null}
curl -X GET "https://api.intentgpt.ai/leadgen?objective=find_marketing_leaders&domain=tech&limit=50" \
-H "X-API-Key: your_api_key"
```

#### Parameters

| Parameter      | Type    | Description                               |
| -------------- | ------- | ----------------------------------------- |
| objective      | string  | Lead generation objective                 |
| domain/website | string  | Company domain filter                     |
| topic/t        | string  | Topic filter                              |
| keyword/k      | string  | Keyword filter                            |
| limit          | integer | Max leads to return (1-1000, default: 10) |

## Lead List Management

### Create Lead List

```bash theme={null}
curl -X POST "https://api.intentgpt.ai/leadgen/lists" \
-H "X-API-Key: your_api_key" \
-H "Content-Type: application/json" \
-d '{
  "name": "Marketing Leaders Q1",
  "objective": "Find marketing decision makers",
  "domain": "saas",
  "limit": 100
}'
```

### Update Lead List

```bash theme={null}
curl -X PUT "https://api.intentgpt.ai/leadgen/lists/list_123" \
-H "X-API-Key: your_api_key" \
-H "Content-Type: application/json" \
-d '{
  "name": "Updated List Name",
  "replace_leads": true,
  "leads": [...]
}'
```

## Priority Levels

| Level | Description                                                                  |
| ----- | ---------------------------------------------------------------------------- |
| Hot   | High-priority prospects with strong buying signals and immediate opportunity |
| Warm  | Qualified prospects showing moderate intent, worth nurturing                 |
| Cold  | Early-stage prospects requiring long-term relationship building              |

## Error Handling

The API uses standardized error responses:

```json theme={null}
{
  "success": false,
  "error": {
    "code": "AUTH_001",
    "message": "Authentication required"
  }
}
```

Common error codes:

* `AUTH_001` - Authentication error
* `CRED_001` - Insufficient credits
* `RATE_001` - Rate limit exceeded
* `REQ_001` - Invalid request
* `SYS_001` - Internal error

## Health Check

Check API system status:

```bash theme={null}
curl -X GET "https://api.intentgpt.ai/health"
```

Returns detailed health information including database connectivity and service status.

## SDKs and Libraries

Official SDKs available:

* [JavaScript/TypeScript](https://github.com/intentgpt/sdk-js)
* [Python](https://github.com/intentgpt/sdk-python)

## Support

Need help? Contact our support team:

* Email: [support@intentgpt.ai](mailto:support@intentgpt.ai)
* Developer Community: [community.intentgpt.ai](https://community.intentgpt.ai)

<Note>
  New users receive 5000 free credits upon API key creation. For enterprise-level usage or custom limits, contact [sales@intentgpt.ai](mailto:sales@intentgpt.ai).
</Note>