> ## 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.

# Client Setup

> Install the TypeScript SDK or call REST from another language.

Use the `influship` package for typed JavaScript and TypeScript requests. For other languages, call the REST API with your HTTP client.

Browse the SDK on [npm](https://www.npmjs.com/package/influship) or [GitHub](https://github.com/Influship/influship-sdk-typescript). For complete apps and runnable workflows, see the [cookbook](/cookbook).

## Install the SDK

<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>

## Configure a server-side client

Set `INFLUSHIP_API_KEY` in your server environment:

```bash theme={null}
export INFLUSHIP_API_KEY="your_api_key_here"
```

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

const client = new Influship({ maxRetries: 0 });
const search = await client.search.create({
  query: 'sustainable fashion creators who explain clothing repair',
  limit: 5,
});

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

The client reads `INFLUSHIP_API_KEY` automatically. You can also pass `apiKey` explicitly. Keep the client in a server action, route handler, backend service, or CLI; keep the key out of browser bundles and version control.

Each result contains `creator`, profile summaries, and `match`. Follow the [Quickstart](/quickstart) to use a returned creator ID in a second request, or run the [creator research app](/cookbook/creator-research-app).

## Handle typed errors

The SDK retries some failures twice by default. The example sets `maxRetries: 0` so your application controls retry behavior.

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

try {
  await client.search.create({ query: 'clothing repair tutorials', limit: 5 });
} catch (error) {
  if (error instanceof RateLimitError) {
    console.error('Rate limited. Retry-After:', error.headers?.get('retry-after'));
  } else if (error instanceof APIError) {
    console.error(error.status, error.code, error.message);
  } else {
    throw error;
  }
}
```

For `429`, `500`, and temporary `503` responses, use bounded retries with a total deadline and honor `Retry-After`. For `402`, check billing before sending another request. For `502 upstream_contract_broken`, stop automatic retries; a source query or validation failure does not confirm account deletion. Use available cached data and contact support if the issue persists. The [Error Handling guide](/guides/error-handling) includes the complete policy and a retry example.

For live Instagram requests, budget for the complete response, including recovery. Recovery uses the request's remaining execution time; it does not start a fresh timeout window. Keep subsequent API retries within your total deadline.

When merging live Instagram profile responses, treat `bio_links` as available valid links. Recovery excludes unusable source entries; an empty array or `external_url: null` does not establish that a creator removed their website. Preserve previously known website data when the new response provides no usable link. See [Instagram profile metadata](/guides/download-instagram-videos#profile-counts-and-omitted-fields).

## Call REST from Python

Install `requests`, then read the same server-side environment variable:

```bash theme={null}
python -m pip install requests
```

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

response = requests.post(
    'https://api.influship.com/v1/search',
    headers={'X-API-Key': os.environ['INFLUSHIP_API_KEY']},
    json={'query': 'creators who teach clothing repair', 'limit': 5},
    timeout=60,
)
response.raise_for_status()
for result in response.json()['data']:
    print(result['creator']['name'], result['match']['reasons'])
```

## Continue with your workflow

| Task | Guide |
| - | - |
| Find more creators like a reference account | [Find similar creators](/concepts/lookalikes) |
| Evaluate known Instagram handles | [Score campaign fit](/cookbook/score-campaign-fit) |
| Resolve profiles and read timestamps | [Understanding creator data](/concepts/creators-vs-profiles) |
| Fetch profiles, videos, or transcripts | [Live platform data](/guides/live-platform-data) |
| Save a selection and review notes | [Saved shortlists](/guides/saved-shortlists) |

<Accordion title="Set up with a coding agent">
  <Prompt description="Install the Influship SDK using this project's existing conventions." actions={["copy", "cursor"]}>
    Add the Influship API to this project.

    First inspect the repository to identify its language, framework, package manager, environment-variable conventions, and existing API client patterns. Preserve those conventions.

    For a TypeScript or JavaScript project:

    1. Install the official `influship` package with the repository's existing package manager.
    2. Configure a server-side Influship client that reads `INFLUSHIP_API_KEY` from the environment.
    3. Add `INFLUSHIP_API_KEY=` to the appropriate example environment file. Never put a real key in source code, generated files, logs, client-side bundles, or version control.
    4. Add a small, reusable example for natural-language creator search using `client.search.create({ query, limit: 5 })`. Keep it behind an existing server-side boundary such as a server action, route handler, backend service, or CLI command.
    5. Set `maxRetries: 0`, then use the SDK's exported error classes to apply bounded retries for 429 and temporary 503 responses. Honor `Retry-After`. Do not automatically retry 402 or `502 upstream_contract_broken`.

    For another language, use the REST API with base URL `https://api.influship.com` and an `X-API-Key` header and follow the project's existing HTTP-client conventions.

    Use [https://docs.influship.com/sdks](https://docs.influship.com/sdks) and [https://docs.influship.com/api-reference](https://docs.influship.com/api-reference) as the contract. Run the relevant local formatting, type-check, and test commands. Verify locally with mocked HTTP first. If `INFLUSHIP_API_KEY` is available, make one creator search with `limit: 1` to verify the integration. Finish by listing the files changed, where I should set `INFLUSHIP_API_KEY`, and the verification result.
  </Prompt>
</Accordion>

The [API Reference](/api-reference) defines method signatures and response schemas. When upgrading, compare it with your installed SDK version.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.