Transient Intelligence

Transient Intelligence — API Integration

Everything you need to integrate the Transient Intelligence API into your product — endpoints, authentication, request shapes, and response handling.

Tools & Artifacts

Download our official API specifications and test collections to jumpstart your integration.

Postman Collection

Pre-configured requests and auth

OpenAPI Spec

YAML schema for auto-generation

Authentication

All API endpoints require the x-api-key header. Every request must include it.

Header

x-api-key: <YOUR_TI_API_KEY>

Create account Get API key

Core Endpoints Reference

Two integration paths are available. Use /answer for inline text — it handles upload, indexing, and query in one call. Use the decoupled /upload → /ask flow for large files or async workloads.

POST/api/models/v1/answerRecommended default

One-call orchestrator. Accepts inline content and a question, handles upload and evidence retrieval internally, and returns a grounded response. Equivalent to ti_run_workflow in MCP.

Request body

Parameter	Type	Required	Description
question	string	Yes	The question to answer from the provided evidence.
input	string	Conditional	Raw text or JSON content to ingest inline. Required unless `session_id` or `input_url` is provided.
input_url	string	Conditional	HTTPS URL to a publicly accessible file. Must not be a local path (`/mnt/data`, `file://`).
session_id	string	No	Reuse an existing indexed session. If provided without a source, queries that session directly.
top_k	integer	No	Number of evidence chunks to retrieve. Default: `10`. Max: `50`. See top_k guide below.
wait_max_ms	integer	No	Max milliseconds to wait for async indexing before returning a retry payload. Default: `10000`. Max: `60000`.
retry_after_seconds	integer	No	Hint returned in retry payloads. Default: `10`.
include_normative	boolean	No	Include `normative_check` and `factual_confidence` in the response. Default: `true`.

cURL

# One-call answer with inline text

curl -X POST "https://api.transientintelligence.com/api/models/v1/answer" \

-H "x-api-key: YOUR_API_KEY" \

-H "Content-Type: application/json" \

-d '{"question": "What was Q3 revenue?", "input": "Q3 revenue reached $1.2M driven by enterprise signups.", "top_k": 5}'

Response

Response — mode: answer_completed

{

"success": true,

"mode": "answer_completed",

"sessionId": "ti-01-session-abc123",

"query": "What was Q3 revenue?",

"answer": { "summary": "Q3 revenue reached $1.2M." },

"totalMatches": 3,

"citations": [

{ "doc_id": "inline_input", "snippet": "Q3 revenue reached $1.2M", "locator": "paragraph 1" }

"factual_confidence": { "label": "Strong", "message": "Answer fully supported by evidence." },

"creditsUsed": 1,

"workflow": { "session_id": "ti-01-session-abc123", "retrieval_ready": true, "waited_ms": 0 }

}

POST/api/models/v1/upload

Ingest source data into a session. Accepts JSON payloads and multipart file uploads. Returns a session_id and optionally a run_id for async tracking.

Supported input types

.pdf

PDF

Text-layer extraction. Async for large files.

.docx

Word

Full document with headings and tables.

.xlsx

Excel

Tabular data across sheets. Processed via Excel pipeline.

.csv

CSV

Flat tabular data. Treated as structured evidence.

.txt

Plain text

Raw text. Fastest indexing path.

.json

JSON

Structured payloads and inline data objects.

Request body

Parameter	Type	Required	Description
input	string	Conditional	Text or JSON content to ingest. Required if no files or `input_url`.
input_url	string	Conditional	HTTPS URL pointing to a file to fetch and ingest server-side.
files	multipart	Conditional	One or more files as multipart form data. Max 30MB default.
sessionId	string	No	Attach to an existing session to append content.
retention_hours	integer	No	How long to retain the indexed session. Subject to platform cap.

cURL — JSON payload

curl -X POST "https://api.transientintelligence.com/api/models/v1/upload" \

-H "x-api-key: YOUR_API_KEY" \

-H "Content-Type: application/json" \

-d '{"input": "Document text content here..."}'

Response

{

"session_id": "ti-01-session-abc123",

"run_id": "run_xyz789",

"retrieval_ready": false,

// retrieval_ready: false means indexing is async. Poll /v1/runs/{run_id} before calling /v1/ask.

"summary": "Ingest complete. Use /v1/ask for retrieval."

}

POST/api/models/v1/ask

Evidence-first query endpoint. Requires a session_id from a prior upload and a question. Returns grounded citations and an optional synthesized answer. Only call once retrieval_ready: true.

Request body

Parameter	Type	Required	Description
session_id	string	Yes	Session ID returned from `/v1/upload`.
question	string	Yes	The question to answer from indexed evidence.
top_k	integer	No	Evidence chunks to retrieve. Default: `10`. Max: `50`. See top_k guide below.
evidence_only	boolean	No	Return only citations without a synthesized answer.
answer_only	boolean	No	Return a concise answer with compact citations only.
include_normative	boolean	No	Include `normative_check` and `factual_confidence`. Default: `true`.

top_k: choosing the right value

Controls how many evidence chunks are retrieved before synthesis. Higher values increase recall but may surface weaker matches. Lower values prioritise precision.

1 – 5

Precision. Use for highly specific, targeted questions.

6 – 15

Balanced. Default range for most integrations.

16 – 50

Recall. Use for broad synthesis across long documents.

cURL

curl -X POST "https://api.transientintelligence.com/api/models/v1/ask" \

-H "x-api-key: YOUR_API_KEY" \

-H "Content-Type: application/json" \

-d '{"session_id": "ti-01-session-abc123", "question": "What was Q3 revenue?", "top_k": 5}'

Response

{

"success": true,

"sessionId": "ti-01-session-abc123",

"query": "What was Q3 revenue?",

"answer": { "summary": "Q3 revenue reached $1.2M." },

"totalMatches": 4,

"citations": [

{ "doc_id": "doc_abc", "snippet": "Q3 revenue reached $1.2M", "locator": "page 3, paragraph 2" }

"factual_confidence": { "label": "Strong", "message": "Answer fully supported by evidence." },

"creditsUsed": 1,

"refund": { "applied": false, "reason": null }

}

GET/api/models/v1/runs/{id}

Poll the status of an asynchronous run. Call after /v1/upload returns retrieval_ready: false. Proceed to /v1/ask once status is completed.

cURL

curl "https://api.transientintelligence.com/api/models/v1/runs/run_xyz789" \

-H "x-api-key: YOUR_API_KEY"

Response

{

"session_id": "ti-01-session-abc123",

"run_id": "run_xyz789",

"status": "completed",

"retrieval_ready": true

}

GET/api/models/v1/runs/{id}/results

Retrieve the final output of a completed run. Use after polling confirms status: completed.

cURL

curl "https://api.transientintelligence.com/api/models/v1/runs/run_xyz789/results" \

-H "x-api-key: YOUR_API_KEY"

Response

{

"session_id": "ti-01-session-abc123",

"run_id": "run_xyz789",

"status": "completed",

"retrieval_ready": true,

"summary": "Ingest complete. Evidence indexed and ready for /v1/ask retrieval."

}

Session management (important)

Reusing the same session_id across unrelated reviews can muddy previous context and make results harder to interpret.

Reuse session_id only for follow-up questions on the same evidence set.
Start a new session when switching documents, review goals, or customer/case boundaries.
Persist session_id per workflow job, not as a global shared default.
In multi-tenant setups, never reuse sessions across tenants or projects.

Next Steps

Workflow & Policy Guide →MCP Integration Quickstart →