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

# SDKs

> Install the TypeScript SDK and start making API calls in minutes

# SDKs

The TypeScript SDK is auto-generated from the OpenAPI spec. It gives you typed methods, request/response models, and automatic error classes — so you spend less time reading docs and more time building.

## TypeScript / JavaScript

### Installation

<Tabs>
  <Tab title="npm">
    ```bash theme={null}
    npm install influship
    ```
  </Tab>

  <Tab title="yarn">
    ```bash theme={null}
    yarn add influship
    ```
  </Tab>

  <Tab title="pnpm">
    ```bash theme={null}
    pnpm add influship
    ```
  </Tab>

  <Tab title="bun">
    ```bash theme={null}
    bun add influship
    ```
  </Tab>
</Tabs>

### Client Setup

```typescript theme={null}
import Influship from 'influship';

const client = new Influship({
  apiKey: process.env.INFLUSHIP_API_KEY,
});
```

If `INFLUSHIP_API_KEY` is set in your environment, you can skip the config object entirely:

```typescript theme={null}
const client = new Influship();
```

### Common Operations

#### Search

Search accepts a natural language query and returns ranked creators. Describe the kind of creator you need — the API handles the matching.

```typescript theme={null}
const results = await client.creators.search({
  query: 'sustainable fashion creators',
  limit: 10,
  filters: {
    followers: { min: 10000, max: 500000 },
    engagement_rate: { min: 2.0 },
  },
});

for (const result of results.data) {
  console.log(result.creator.name, result.match.score);
}
```

Start with a small limit (5-10) while prototyping. Larger limits cost more credits and usually return diminishing-value results past the top 15-20.

#### Lookalike

Find creators similar to ones you already know. You can weight seeds to influence which traits matter more in the results.

```typescript theme={null}
const similar = await client.creators.lookalike({
  seeds: [
    { platform: 'instagram', username: 'fitness_coach_jane', weight: 1.0 },
    { platform: 'instagram', username: 'wellness_daily', weight: 0.5 },
  ],
  limit: 15,
});
```

A higher weight means the API leans more heavily on that seed's profile characteristics. Use this when one seed is a better example of what you want than the others.

#### Campaign Match

Score how well specific creators fit a campaign brief. Each result includes a decision (strong fit, moderate fit, or weak fit) and a numeric score.

```typescript theme={null}
const fit = await client.creators.match({
  creator_ids: ['creator-uuid-1', 'creator-uuid-2'],
  intent: {
    query: 'Promote a new plant-based protein bar',
    context: 'Target audience is health-conscious millennials aged 22-35',
  },
});

for (const result of fit.data) {
  console.log(result.match.decision, result.match.score);
}
```

#### Profile Lookup

Retrieve a single creator profile by platform and username.

```typescript theme={null}
const profile = await client.profiles.get('instagram', 'jamietravels');
```

#### Batch Lookup

Look up multiple profiles in a single request. This is more efficient than calling `profiles.get` in a loop — one request, one billing event.

```typescript theme={null}
const profiles = await client.profiles.lookup({
  profiles: [
    { platform: 'instagram', username: 'jamietravels' },
    { platform: 'tiktok', username: 'chef_marco' },
  ],
});
```

Profile lookups are cheap but add up at scale. Cache these responses if your use case allows it — creator data doesn't change often.

#### Creator Email Lookup

Fetch known email addresses for creators. Identify each creator by Influship `creator_id` or by `platform` + `username` — you can mix both in one request. Response rows preserve the input order.

```typescript theme={null}
const emails = await client.creatorEmails.lookup({
  creators: [
    { platform: 'instagram', username: 'jamietravels' },
    { creator_id: '123e4567-e89b-12d3-a456-426614174000' },
  ],
});
```

Emails can be `unvalidated`, so check each `status` before treating an address as deliverable. You're charged only for resolved creators that return at least one email.

### Error Handling

The SDK exports typed error classes so you can handle failures precisely.

```typescript theme={null}
import Influship, { APIError, RateLimitError } from 'influship';

try {
  const results = await client.creators.search({ query: 'fitness' });
} catch (error) {
  if (error instanceof RateLimitError) {
    console.log('Account rate limited, retry after:', error.retryAfter);
  } else if (error instanceof APIError && error.status === 503) {
    console.log('Temporary upstream issue, retry after:', error.headers?.get('retry-after'));
  } else if (error instanceof APIError) {
    console.log('API error:', error.status, error.message);
  }
}
```

`429 rate_limit_exceeded` means your API key hit its account-level quota. `503 service_unavailable` on live data endpoints means a temporary upstream/platform issue; retry it with backoff and use `Retry-After` when present.

See [Error Handling](/guides/error-handling) for the full error reference.

## Python

There is no official Python SDK yet. Use the REST API directly with `requests` or `httpx`.

```python theme={null}
import requests

response = requests.post(
    'https://api.influship.com/v1/search',
    headers={'X-API-Key': 'your_api_key'},
    json={
        'query': 'sustainable fashion creators',
        'limit': 10,
    },
)

data = response.json()
for result in data['data']:
    print(result['creator']['name'], result['match']['score'])
```

## API Reference

The [API Reference](/api-reference) is generated from the same spec as the SDK. Use it for the most up-to-date method signatures and response shapes. If the SDK types and the reference ever seem to disagree, the reference reflects the latest deployed version.