Submit samples to a project via API

Send LLM interaction samples to a specific project. The API persists a Sample
and enqueues a pipeline run to populate auto-grades. The response returns the
sampleId immediately.

Endpoint

• Method: POST
• URL:
  https://boltfoundry.com/api/2025-10/teams/:teamSlug/projects/:projectSlug/samples/ingest
• Example with placeholders:
  https://boltfoundry.com/api/2025-10/teams/example-team/projects/example-project/samples/ingest

Auth

• Header: X-BF-API-Key: bf_write_only_key_<id>
• Content type: Content-Type: application/json

Request body

Required

• userInput (string)
• assistantResponse (string)

Optional

• assistantContext (string) - conversation context before the turn
• label (string) - human-readable name; autogenerated if omitted
• referenceData (object) - arbitrary JSON to help you track the sample
• runMetadata (object) - extra JSON passed to the underlying run
• requestId (string) - idempotency key (see below)

curl example

curl -X POST "https://boltfoundry.com/api/2025-10/teams/example-team/projects/example-project/samples/ingest" \
  -H "Content-Type: application/json" \
  -H "X-BF-API-Key: bf_write_only_key_<your_api_key_id>" \
  --data-raw '{
    "userInput": "Summarize the attached report",
    "assistantResponse": "Here is the summary...",
    "label": "Customer report QA #42",
    "referenceData": { "ticketId": 42 }
  }'

Response

• 200 OK
  • Body: { "sampleId": "sample:..." }

Idempotency (optional)

Provide a stable id to dedupe retries.

• Body field: requestId: "<your-id>"
• Or header: X-BF-Event-ID: <your-id>

If the id matches a previous request for the same project, the API returns the
existing sampleId.

Errors

• 400 invalid_payload - body is missing required fields or has wrong types
  • Example:
    { "error": "invalid_payload", "message": "userInput is required and must be a string" }
• 401 missing_api_key - no X-BF-API-Key header present
• 401 invalid_api_key - key format or id is invalid
• 403 organization_mismatch - :teamSlug in the URL does not match the API
  key's organization
• 404 project_not_found - :projectSlug is unknown for the organization
• 405 method_not_allowed - method is not POST
• 500 internal_error - unexpected server error

Notes

• API version: 2025-10 (current)
• Auto-grades are linked asynchronously when the run completes; the sample is
  usable immediately for adding reference grades.