Quick Start

Create a Technical Session, inspect its validation, continue the recommended work, and retrieve its artifacts. You need an Ivorleaf API key and about five minutes.

1. Get an API key

Ivorleaf API keys are issued through developer onboarding; there is no public self-service key generator. Request an API key, then keep it server-side.

2. Set your environment

Production API base URLhttps://api.ivorleaf.io

Keep the API key out of source code and shell history. Set these variables in your current shell:

export IVORLEAF_API_BASE_URL="https://api.ivorleaf.io"
export IVORLEAF_API_KEY="ivl_..."

All examples use API-key authentication through the Bearer scheme:

Authorization: Bearer $IVORLEAF_API_KEY

X-API-Key: $IVORLEAF_API_KEY is also supported by the API, but Bearer authentication is preferred. X-Ivorleaf-Client is optional for direct API use; when omitted, the backend treats the client as api.

3. Create a Technical Session

The public product action is Create a Technical Session. Its current API path is POST /v1/tutor.

The only required request property is query. This prompt asks Ivorleaf to review a realistic production decision, validate its assumptions, and recommend an implementation path:

CREATE_RESPONSE=$(curl --silent --show-error --fail-with-body \
  --request POST \
  --url "$IVORLEAF_API_BASE_URL/v1/tutor" \
  --header "Authorization: Bearer $IVORLEAF_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "query": "Review a production deployment approach for a multi-tenant Next.js API on AWS ECS Fargate with PostgreSQL. Identify readiness gaps, validate security and rollback assumptions, and propose an implementation plan with evidence-backed recommendations."
  }')

SESSION_ID=$(printf '%s' "$CREATE_RESPONSE" | jq -r '.session_id')
test -n "$SESSION_ID" && test "$SESSION_ID" != "null"
printf 'Created Technical Session: %s\n' "$SESSION_ID"

This cURL example requires jq. Complete executable versions with HTTP and response checks are included in the repository at examples/curl/quick-start.sh, examples/typescript/quick-start.ts, and examples/python/quick_start.py.

The equivalent TypeScript request uses native fetch from a server-side process:

const response = await fetch(`${process.env.IVORLEAF_API_BASE_URL}/v1/tutor`, {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.IVORLEAF_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    query: "Review a production deployment approach for a multi-tenant Next.js API on AWS ECS Fargate with PostgreSQL. Identify readiness gaps, validate security and rollback assumptions, and propose an implementation plan with evidence-backed recommendations.",
  }),
});
if (!response.ok) throw new Error(`Ivorleaf request failed: ${response.status}`);
const technicalSession = await response.json();
const sessionId = technicalSession.session_id;

Python uses requests:

import os
import requests

response = requests.post(
    f"{os.environ['IVORLEAF_API_BASE_URL'].rstrip('/')}/v1/tutor",
    headers={"Authorization": f"Bearer {os.environ['IVORLEAF_API_KEY']}"},
    json={"query": "Review a production deployment approach for a multi-tenant Next.js API on AWS ECS Fargate with PostgreSQL. Identify readiness gaps, validate security and rollback assumptions, and propose an implementation plan with evidence-backed recommendations."},
    timeout=120,
)
response.raise_for_status()
technical_session = response.json()
session_id = technical_session["session_id"]

Run the TypeScript version with native fetch:

npx tsx examples/typescript/quick-start.ts

Or install requests and run the Python version:

python -m pip install requests
python examples/python/quick_start.py

4. Inspect validation

No live API key was available when this guide was generated, so there is no fabricated response sample. The following fields are verified from TutorResponse and the FastAPI response construction:

| Field | Meaning | | --- | --- | | session_id | Stable identifier for the new Technical Session. Save it for every following request. | | query | The technical task used to create the session. | | answer | The generated technical analysis. | | sources and lessons_used | Sources or validated evidence selected for the response. These are arrays and may be empty. | | technical_analysis | Optional structured technical analysis when the generation pipeline produces it. | | validated_technical_workflows | Optional validated workflow recommendations produced for the task. | | available_actions and followup_suggestions | Optional continuation signals. The official continuation mechanism is the orchestration endpoint below. | | unified_experience | Optional current experience state, including artifact state initialized for the session. |

The schema also contains learning and media fields. They are not required to understand the initial developer journey.

When technical_analysis is present, inspect each analysis packet's validation_status, confidence, assumptions, unknowns, risks, and sources. The current analysis validation fields are grounded, official_documentation_used, conflicting_sources_detected, human_review_recommended, and validation_level.

const analyses = technicalSession.technical_analysis?.analyses ?? [];
const requiresReview = analyses.some(
  (analysis: { validation_status?: { human_review_recommended?: boolean } }) =>
    analysis.validation_status?.human_review_recommended === true,
);

if (requiresReview) {
  // Route to your review process; do not auto-execute technical work.
}

See Validation Responses before using validation metadata as an automation gate.

5. Recommend the next step

Creating a Technical Session starts new work. Recommend and Continue operate on that existing session.

First ask Ivorleaf to evaluate the saved session state and recommend what should happen next:

RECOMMEND_RESPONSE=$(curl --silent --show-error --fail-with-body \
  --request POST \
  --url "$IVORLEAF_API_BASE_URL/v1/history/$SESSION_ID/orchestrate" \
  --header "Authorization: Bearer $IVORLEAF_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{"intent":"recommend"}')

The verified response fields are session_id, mode, and orchestration. In Recommend mode, orchestration can contain recommendations, recommended_action, recommended_title, reason, validation-aware warnings, and a saved last_recommendation. Their exact presence and values depend on the Technical Session.

6. Continue the recommendation

Continue asks Ivorleaf to act on the recommendation associated with the existing Technical Session:

CONTINUE_RESPONSE=$(curl --silent --show-error --fail-with-body \
  --request POST \
  --url "$IVORLEAF_API_BASE_URL/v1/history/$SESSION_ID/orchestrate" \
  --header "Authorization: Bearer $IVORLEAF_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{"intent":"continue"}')

The backend maps intent: "continue" to execution mode. The response still has session_id, mode, and orchestration; execution details can appear in orchestration.continuation, orchestration.executed_actions, orchestration.chain, and orchestration.warnings. Validation can require human review, in which case an action may be skipped and explained in warnings.

Advanced controls such as requested_action, execute, trigger, source, auto_chain, and max_chain_steps are intentionally outside this Quick Start. Recommend first, then Continue.

7. Retrieve the Technical Session

Read the current saved state after continuation:

curl --silent --show-error --fail-with-body \
  --url "$IVORLEAF_API_BASE_URL/v1/history/$SESSION_ID" \
  --header "Authorization: Bearer $IVORLEAF_API_KEY"

The source implementation returns id, query, subject, answer, validated sources, citation_warnings, technical workflow state, and unified_experience, among other fields. This route currently has no declared OpenAPI response model, so consumers should use only documented fields and tolerate additive fields.

8. List artifacts

Artifacts are durable outputs associated with the Technical Session:

curl --silent --show-error --fail-with-body \
  --url "$IVORLEAF_API_BASE_URL/v1/history/$SESSION_ID/artifacts" \
  --header "Authorization: Bearer $IVORLEAF_API_KEY"

The source implementation returns session_id, artifact_count, artifacts, and unified_experience. The list can be empty. Each artifact can be retrieved later with GET /v1/history/{session_id}/artifacts/{artifact_id}.

Errors

FastAPI error bodies commonly contain a detail field, while validation errors use FastAPI's structured validation response. Provider and internal paths are not guaranteed to share one envelope, so handle status codes before parsing a specific shape.

| Status | What it means | What to do | | --- | --- | --- | | 401 | The API key is missing, malformed, unknown, or otherwise cannot be authenticated. Source messages include Invalid API key. | Confirm the Bearer header and key value. | | 403 | The key is revoked, expired, inactive, or not allowed for the supplied client. Source messages include API key revoked, API key expired, and API client is not allowed for this key. | Request a valid key or use an allowed client. | | 422 | FastAPI could not validate the path, parameters, or JSON body. | Check the request against the API Reference. | | 429 | A per-minute request limit, billing-period session limit, workflow limit, or upstream provider rate limit was reached. | Inspect usage status, then retry only when the relevant limit permits. | | 5xx | Ivorleaf, persistence, or an upstream model/provider failed. Some provider failures are returned as 502; unexpected tutor failures use 500. | Retry transient failures with backoff and preserve the original session_id when continuing existing work. |

Check API-key usage with GET /v1/api/usage/status. List recent Technical Sessions with GET /v1/history.

Quick Start

1. Get an API key

2. Set your environment

3. Create a Technical Session

4. Inspect validation

5. Recommend the next step

6. Continue the recommendation

7. Retrieve the Technical Session

8. List artifacts

Errors

Where to go next