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

# API Reference

Our API allows you to programmatically access and leverage your professional network data, search profiles and companies, and map relationships across your team's connections.

<Note>
  **v3 is now live.** v3 is built on a refreshed dataset with \~98% fewer duplicate and corrupted profiles. v2 endpoints will be deprecated on **July 15, EOD UTC** — see the [Migrating to v3](/docs/getting-started/migrating-to-v3) guide.
</Note>

## Before You Begin

To use The Swarm API, you'll need:

1. **An active Swarm account** - Sign up at [app.theswarm.com](http://app.theswarm.com)
2. **Team owner or admin role** - API access requires owner or admin permissions
3. **Appropriate plan** - API access is included in the Premium plan (14-day free trial available)
4. **An API key** - Generate your key from Team Settings

## Getting Your API Key

Follow these steps to obtain your API key:

1. Navigate to **Team Settings** by clicking your Team name in the top-left corner of the sidebar
2. Go to the [**API**](https://app.theswarm.com/team-settings/api) tab
3. Click **Generate API Key** to create your key
4. Copy the generated key to your clipboard

## Authentication

All API requests must include your API key in the headers:

```text theme={null}
x-api-key: your_api_key_here
```

This authenticates your requests and provides access to your team-specific data, including profiles, lists, tags, and network connections.

### Partner accounts: acting on behalf of a child team

If you're a Swarm Partner, you can execute a request in the context of a child team you manage by adding the `x-authenticate-team` header:

```text theme={null}
x-authenticate-team: <child_team_id>
```

Omit the header to run the request as the team that owns the API key (default). This header is supported by the [Search Profiles](/docs/endpoints/v3/search-profiles), [Fetch Profile](/docs/endpoints/v3/fetch-profile), [Search Companies](/docs/endpoints/v3/search-companies), [Fetch Company](/docs/endpoints/v3/fetch-company), [Relationships](/docs/endpoints/v3/relationships), and [Add Connector](/docs/endpoints/v3/add-connector) endpoints. See [Create Team](/docs/endpoints/v3/create-team) for how to obtain a `child_team_id`.

**Example Request:**

```text theme={null}
curl -X POST https://api.theswarm.com/v2/profiles/search \
  -H "x-api-key: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "query": {
      "match_all": {}
    },
    "limit": 10
  }'
```

## Available Endpoints

The Swarm API provides five core endpoints to help you search, retrieve, and analyze professional network data:

### **Search Profiles**

Search through profiles using powerful OpenSearch query capabilities. Filter by job titles, locations, industries, skills, and more. Perfect for finding specific professionals across your network.

[View Documentation →](/docs/endpoints/search-profiles)

### **Fetch Profiles**

Retrieve detailed information about specific profiles by their IDs. Get comprehensive data including employment history, education, contact information, and connection details.

[View Documentation →](/docs/endpoints/fetch-profile)

### **Search Companies**

Find companies based on various criteria such as industry, size, location, and more. Access company intelligence data across your network.

[View Documentation →](/docs/endpoints/search-companies)

### **Fetch Companies**

Get detailed company information including employee counts, locations, industries, and associated profiles from your network.

[View Documentation →](/docs/endpoints/fetch-company)

### **Network Mapper**

Discover pathways and connections between your team and target profiles or companies. Visualize relationship strength and find warm introductions.

[View Documentation →](/docs/endpoints/network-mapper)

## Security Best Practices

Your API key is a powerful credential. Protect it like a password:

* **Keep it private** - Never share your API key in public repositories (like GitHub) or client-side code
* **Protect your access** - Unauthorized use can compromise your data and system integrity
* **Rotate regularly** - Generate new keys periodically and revoke old ones
* **Monitor usage** - Track API calls to detect any unusual activity

## Getting Started Tips

When beginning with the API, we recommend:

1. **Start small** - Test with a small batch of requests first to validate your setup
2. **Review the mapping** - Understand the [field mappings](/docs/enrichment-data/profile/mappings-v3) before building complex queries
3. **Check examples** - Review our [example queries](/docs/examples/search-endpoint) for common use cases
4. **Mind rate limits** - Be aware of [rate limits](/docs/api-reference/rate-limiting) to avoid throttling
5. **Use pagination** - For large result sets, utilize pagination tokens for efficient data retrieval

## Encoding Standards

When working with the API, note these encoding conventions:

* **URLs** - Always stored and returned encoded using `%<hex>` format for special characters
* **Slugs** - Stored, returned, and sent in requests decoded, exactly as entered
* **Recommendation** - Use encoded URLs and decoded slugs in all requests

## Need Help?

* **Support** - Contact our team at [support@theswarm.com](mailto:support@theswarm.com)
* **Examples** - Check out example for common patterns
* **Pricing** - Learn more about [plans and pricing](https://www.theswarm.com/pricing)