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

# Get started with Orbit Search: your first API call

> Get an API key from the Orbit dashboard, run a search with a plain-English query, and fetch a full profile record.

This guide walks you through the three steps you need to make your first working Orbit Search request: getting an API key, running a search, and reading a profile. By the end you'll have a bearer token, a search result, and a structured profile object — all from the API base URL `https://api.orbitsearch.com`.

<Steps>
  <Step title="Get an API key">
    Log in to the [Orbit developer dashboard](https://developer.orbitsearch.com/dashboard/keys) and generate a personal API key with the `search:read` and `profile:read` scopes.

    Copy the raw key when the dashboard shows it. It starts with `sk_orb_` and is shown only once.

    ```bash theme={"dark"}
    export ORBIT_API_KEY="sk_orb_REDACTED"
    ```

    <Warning>
      The public developer API does not create your first key. You need a dashboard-issued `sk_orb_...` key before making API requests. Store it in a secrets manager or environment variable before closing the dashboard modal.
    </Warning>
  </Step>

  <Step title="Run a search">
    Use `POST /v2/developer/search` to search the Orbit index in plain English. Pass your API key as a bearer token. The `query` and `numUsers` fields are both required.

    <CodeGroup>
      ```bash cURL theme={"dark"}
      curl -X POST "https://api.orbitsearch.com/v2/developer/search" \
        -H "Authorization: Bearer sk_orb_REDACTED" \
        -H "Idempotency-Key: your-unique-request-id" \
        -H "Content-Type: application/json" \
        -d '{"query":"founders in sf","numUsers":10}'
      ```

      ```javascript JavaScript theme={"dark"}
      const response = await fetch(
        "https://api.orbitsearch.com/v2/developer/search",
        {
          method: "POST",
          headers: {
            Authorization: "Bearer sk_orb_REDACTED",
            "Idempotency-Key": crypto.randomUUID(),
            "Content-Type": "application/json",
          },
          body: JSON.stringify({ query: "founders in sf", numUsers: 10 }),
        }
      );

      const data = await response.json();
      ```
    </CodeGroup>

    A successful response looks like this:

    ```json theme={"dark"}
    {
      "status": "success",
      "searchId": "uuid",
      "payload": {
        "users": []
      }
    }
    ```

    Each object in `payload.users` includes an `id` you can use to fetch the full profile. The response also includes the `X-Developer-API-Credits-Remaining` header so you can track how many credits you have left.

    <Tip>
      Include an `Idempotency-Key` header on every search request. If your client retries after a network error, the same key prevents you from being charged twice for the same search. Use a fresh key for each logically distinct request.
    </Tip>

    <Note>
      Search costs 2 credits per successful request. If the search returns no results or fails, the reservation is refunded and no credits are consumed. Requests that exceed your credit balance return a `402` with code `developer_api_credits_insufficient` before any search work begins.
    </Note>
  </Step>

  <Step title="Read a profile">
    Take an `id` from your search results and pass it to `GET /v2/developer/profiles/:id`. Each profile read costs 1 credit; not-found and failed reads are refunded.

    <CodeGroup>
      ```bash cURL theme={"dark"}
      # Extract the first profile id from your search response, then fetch the profile
      SEARCH_RESPONSE=$(
        curl -s -X POST "https://api.orbitsearch.com/v2/developer/search" \
          -H "Authorization: Bearer sk_orb_REDACTED" \
          -H "Content-Type: application/json" \
          -d '{"query":"founders in sf","numUsers":10}'
      )

      PROFILE_ID=$(echo "$SEARCH_RESPONSE" | jq -r '.payload.users[0].id')

      curl "https://api.orbitsearch.com/v2/developer/profiles/$PROFILE_ID" \
        -H "Authorization: Bearer sk_orb_REDACTED"
      ```

      ```javascript JavaScript theme={"dark"}
      // After getting searchData from the search step above:
      const profileId = searchData.payload.users[0].id;

      const profileResponse = await fetch(
        `https://api.orbitsearch.com/v2/developer/profiles/${profileId}`,
        {
          headers: {
            Authorization: "Bearer sk_orb_REDACTED",
          },
        }
      );

      const profile = await profileResponse.json();
      ```
    </CodeGroup>

    The profile response contains a structured, public-safe DTO:

    ```json theme={"dark"}
    {
      "status": "success",
      "payload": {
        "id": "orbit-profile-id",
        "displayName": "Ada Lovelace",
        "personName": "Ada Lovelace",
        "aliases": ["Ada Byron", "Countess Ada"],
        "avatarUrl": "https://...",
        "profileUrl": "https://orbitsearch.com/ada",
        "verified": true,
        "location": {
          "city": "San Francisco, CA, US"
        },
        "headline": {
          "jobTitle": "Founder",
          "companyName": "Example Co",
          "schoolName": "Example University"
        },
        "sections": {
          "basic": {
            "items": [
              {
                "kind": "school",
                "title": "Graduated from Example University in 2018",
                "school": "Example University",
                "year": 2018
              },
              {
                "kind": "location",
                "title": "San Francisco, CA",
                "location": "San Francisco, CA"
              }
            ]
          },
          "personalLife": null,
          "jobs": null,
          "education": null,
          "passions": null,
          "worldview": null,
          "accomplishments": null,
          "controversies": null,
          "bestQualities": null,
          "netWorth": null,
          "portfolio": null,
          "families": null
        }
      }
    }
    ```

    The profile DTO exposes a public-safe allowlist of fields. It does not include raw contact details, phone numbers, internal moderation metadata, or profile-owner-only fields. Profiles may also include optional contribution sections such as `mediaCredits`, `musicCredits`, `researchPapers`, `githubRepos`, and `books` when public contribution data is available.
  </Step>
</Steps>