FastGPTFastGPT

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:

  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.

TypeScopeManagement
App keyChat and chat management endpoints for its bound app, including chat logs, chat files, and Sandbox filesApp administrators view, create, and manage all keys on the same app
Personal keyTeam resources accessible to the owning member on endpoints that accept API keysMembers 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"}]}
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.

SymptomCheck
Authentication or permission errorKey, team, member status, and resource permissions
Invalid application IDComplete appId and access to the selected resource
404FastGPT instance address and /api/v2/chat/completions path
Model or quota failureApplication 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 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: 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.

Edit on GitHub

Last updated

On this page

Put your business knowledge to work with AI

Import company documents and build accurate, reliable, traceable AI answers.