# API getting started: make your first request

> Configure a service address, member API key, and application ID, then call a published application.

Source: https://doc.fastgpt.io/openapi/intro
Last Updated: 2026-11-13

## Prerequisites

Find the current endpoint contracts and documentation links on [API reference addresses](https://doc.fastgpt.io/openapi/api-reference).

Prepare a debugged, published application and available model quota, then create or manage API keys in either location:

1. **Account → API Keys**: manage personal keys for the current member (visible to members granted the **Create API Keys** permission under **Account → Team management → Permissions**).
2. **Studio → Target App → Publish Channels → API Access**: switch between **App keys** (FastGPT 4.18.0 or later) and **Personal keys**.

Legacy keys that store an `appId` remain personal keys. That ID is only the default App for `chat/completions`; the request body or SDK suffix can override it, and the owning member’s permissions still apply. Only explicitly created App keys enforce the App binding described below.

| Type         | Scope                                                                                                    | Management                                                           |
| ------------ | -------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------- |
| App key      | Chat and chat management endpoints for its bound app, including chat logs, chat files, and Sandbox files | App administrators view, create, and manage all keys on the same app |
| Personal key | Team resources accessible to the owning member on endpoints that accept API keys                         | Members manage their own keys                                        |

An app key grants access independently of its owning member's app permissions as long as the key, member, team, and bound app remain valid. Personal keys support `authProxy` when enabled by the team owner (FastGPT >= v4.15.0; see [identity proxy](https://doc.fastgpt.io/openapi/identity-proxy)), while app keys identify external users via `customUid`. When the team has an active subscription usage plan, you can configure **Max usage points** and **Expiration time** when creating or editing a key. Store keys on a trusted server or in a secret manager.

## First request

Set `FASTGPT_ORIGIN` to your FastGPT instance and copy `appId` from the application details URL (with a 4.18.0+ app key, `appId` can be omitted because the server uses the bound app). This request calls the published version through `/api/v2/chat/completions` (`v2` is recommended; `/api/v1/chat/completions` is retained for legacy compatibility):

```bash
export FASTGPT_ORIGIN='https://cloud.fastgpt.io'
export FASTGPT_API_KEY='YOUR_API_KEY'
export FASTGPT_APP_ID='YOUR_APP_ID'
curl --fail-with-body "$FASTGPT_ORIGIN/api/v2/chat/completions" \
  -H "Authorization: Bearer $FASTGPT_API_KEY" \
  -H 'Content-Type: application/json' \
  --data @- <<EOF
{"appId":"$FASTGPT_APP_ID","stream":false,"messages":[{"role":"user","content":"Hello"}]}
EOF
```

## Response

A successful call returns JSON. Plain-text output is in `choices[0].message.content`, and `id` identifies the conversation. Content depends on the published application; parse multimodal or detailed results according to the current generated contract. Inspect `error` and the business result. Use usage records for billing information.

| Symptom                            | Check                                                           |
| ---------------------------------- | --------------------------------------------------------------- |
| Authentication or permission error | Key, team, member status, and resource permissions              |
| Invalid application ID             | Complete `appId` and access to the selected resource            |
| 404                                | FastGPT instance address and `/api/v2/chat/completions` path    |
| Model or quota failure             | Application model settings, service status, and available quota |

## Application selection and SDKs

The chat completions endpoint supports OpenAI-compatible requests and ordinary text responses. Detailed events and other endpoints follow FastGPT contracts. When integrating via the official OpenAI SDK, set `baseURL` to your FastGPT instance address plus `/api/v2` and supply `appId`:

#### Python SDK

```python
import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["FASTGPT_API_KEY"],
    base_url=f"{os.environ['FASTGPT_ORIGIN'].rstrip('/')}/api/v2"
)

response = client.chat.completions.create(
    model="fastgpt",  # The published application selects the model.
    messages=[{"role": "user", "content": "Introduce yourself"}],
    stream=False,
    extra_body={"appId": os.environ["FASTGPT_APP_ID"]}
)

print(response.choices[0].message.content)
```

#### Node.js SDK

```typescript
import OpenAI from 'openai';

const client = new OpenAI({
  apiKey: process.env.FASTGPT_API_KEY!,
  baseURL: `${process.env.FASTGPT_ORIGIN!.replace(/\/$/, '')}/api/v2`
});

async function main() {
  const request: OpenAI.Chat.Completions.ChatCompletionCreateParamsNonStreaming & {
    appId: string;
  } = {
    model: 'fastgpt',
    messages: [{ role: 'user', content: 'Introduce yourself' }],
    appId: process.env.FASTGPT_APP_ID!,
    stream: false
  };
  const response = await client.chat.completions.create(request);
  console.log(response.choices[0].message.content);
}

main().catch(console.error);
```

With an app key, omit `appId` and `sourceType` on supported chat and chat management endpoints (the server uses the bound app and fixes `sourceType` to `app`; select **app API key (no appId required)** in the generated API reference to inspect its parameters). With a personal key in third-party tools that accept only a single API key string, use the `<apiKey>-<appId>` composite format; FastGPT resolves target applications in order of request body `body.appId` -> Bearer header suffix -> default application saved on a legacy personal key.

### List sessions with an app key

With an app key, `/api/core/chat/history/getHistories` queries API-source sessions for the bound app. Omit `appId`, `sourceType`, and `source`:

```bash
export FASTGPT_ORIGIN='https://cloud.fastgpt.io'
export FASTGPT_APP_API_KEY='YOUR_APP_API_KEY'
curl --fail-with-body "$FASTGPT_ORIGIN/api/core/chat/history/getHistories" \
  -H "Authorization: Bearer $FASTGPT_APP_API_KEY" \
  -H 'Content-Type: application/json' \
  --data @- <<EOF
{"offset":0,"pageSize":20}
EOF
```

* Offset pagination: pass `offset` starting at `0`.
* Page pagination: omit `offset` and pass `pageNum` starting at `1` (for example `{"pageNum": 2, "pageSize": 20}`); `offset` takes precedence when both are provided.
* `pageSize` defaults to `20` and caps at `500` (larger values clamp to `500`); omitting pagination parameters returns the first page.
* Filter time ranges optionally with `startCreateTime`, `endCreateTime`, `startUpdateTime`, and `endUpdateTime`.

## Next steps

[Business system app integration](https://doc.fastgpt.io/openapi/best-practices/app-integration): connect your product with an app key and the OpenAI SDK, identify users with `customUid`, and manage chat history.

[Datasets](https://doc.fastgpt.io/openapi/dataset) and [identity proxy](https://doc.fastgpt.io/openapi/identity-proxy). Historical handwritten parameters remain in the [archive](https://doc.fastgpt.io/openapi/legacy).
