API getting started: make your first request
Configure a service address, member API key, and application ID, then call a published application.
Prerequisites
Find the current endpoint contracts and documentation links on API reference addresses.
Prepare a debugged, published application and available model quota, then create or manage API keys in either location:
- Account → API Keys: manage personal keys for the current member (visible to members granted the Create API Keys permission under Account → Team management → Permissions).
- 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), 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):
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"}]}
EOFResponse
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:
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)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:
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
offsetstarting at0. - Page pagination: omit
offsetand passpageNumstarting at1(for example{"pageNum": 2, "pageSize": 20});offsettakes precedence when both are provided. pageSizedefaults to20and caps at500(larger values clamp to500); omitting pagination parameters returns the first page.- Filter time ranges optionally with
startCreateTime,endCreateTime,startUpdateTime, andendUpdateTime.
Next steps
Business system app integration: connect your product with an app key and the OpenAI SDK, identify users with customUid, and manage chat history.
Datasets and identity proxy. Historical handwritten parameters remain in the archive.
Last updated