Quickstart

Get from zero to your first answer in about two minutes.

1. Generate an API key

API keys are created from the app, not the API:

Open Settings → API Keys.
Click Create key, give it a name, and (optionally) mark it read-only.
Copy the key - it looks like ffk_… and is shown only once.

A key acts with your own permissions: an admin’s key can do what an admin can, a regular user’s key cannot. A read-only key can ask questions but cannot upload or change anything.

2. Authenticate

Send the key on every request in the X-API-Key header - the value is just the key:

X-API-Key: ffk_your_key_here

A legacy form, Authorization: Api-Key <your-key>, is also accepted for existing integrations, but new code should use X-API-Key.

3. Your first call - ask a question

The simplest endpoint answers a single question grounded in your organization’s knowledge. No session, nothing to set up:

curl -X POST https://api.full-fill.ai/api/v2/chat/ask/ \
  -H "X-API-Key: ffk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"question": "What is our data retention policy?"}'

{
  "answer": "We retain customer data for 24 months…",
  "sources": [{ "filename": "security-policy.pdf", "page_number": 4, "content": "…" }],
  "session_id": null
}

If you get 200 with an answer, your key works. 🎉

Multi-turn conversations

/chat/ask/ is stateless by default (session_id comes back null). For a conversation that remembers context, create a session and reuse its id:

# 1. Create a session - returns its id
curl -X POST https://api.full-fill.ai/api/v2/chat/sessions/ -H "X-API-Key: ffk_…"
# → { "id": 42, ... }

# 2. Ask within it (context is carried across turns)
curl -X POST https://api.full-fill.ai/api/v2/chat/ask/ \
  -H "X-API-Key: ffk_…" -H "Content-Type: application/json" \
  -d '{"question": "And for EU customers?", "session_id": 42}'

You can also add turns directly with POST /chat/sessions/{id}/messages/, and list your conversations with GET /chat/sessions/.

Working with questionnaires

# Upload a questionnaire (multipart)
curl -X POST https://api.full-fill.ai/api/v2/filler/questionnaires/ \
  -H "X-API-Key: ffk_…" \
  -F "files=@questionnaire.xlsx"

# Poll processing status until answers are ready
curl https://api.full-fill.ai/api/v2/filler/questionnaires/{id}/answer-progress/ \
  -H "X-API-Key: ffk_…"
# → { "status": "generating", "answers_expected": 40, "answers_received": 12, "percent": 30 }

# Read the structure, then the answers
curl https://api.full-fill.ai/api/v2/filler/questionnaires/{id}/structure/ -H "X-API-Key: ffk_…"
curl https://api.full-fill.ai/api/v2/filler/questionnaires/{id}/answers/   -H "X-API-Key: ffk_…"

The answers endpoint returns a full array of questions with their answers. Narrow it with ?tab=<name> and ?section=<name> query params.

Adding knowledge to the repository

# Upload a file to your knowledge base
curl -X POST https://api.full-fill.ai/api/v2/repository/files/ \
  -H "X-API-Key: ffk_…" \
  -F "files=@handbook.pdf"

# Check processing status via the file list (status, processing_percent per file)
curl "https://api.full-fill.ai/api/v2/repository/files/?page=1&page_size=50" \
  -H "X-API-Key: ffk_…"

Uploading to the repository may require repository-manager permission depending on your organization’s settings; if you get a 403, ask an admin to enable member uploads or use an admin key.

Pagination & errors

Pagination - paginated lists (repository files, chat sessions) accept ?page=<n>&page_size=<n> and return { count, next, previous, results }. The questionnaire list and a questionnaire’s answers are returned as full arrays.
Errors - {"error": "..."} with a conventional status: 400 invalid input, 403 not permitted / no active license, 404 not found, 429 quota exceeded.