TRtraversal
External API

Create a session

Changed on

Start a new investigation session. Returns 200 if an identical idempotency key was already used.

post/v1/sessions

Request

  • Base URL
    https://api.traversal.com (the document declares no server; this is the origin it was published from)
  • URL
    https://api.traversal.com/v1/sessions
  • Auth
    none declared

Request body

titlestring nullable

A short, human-readable label for the session. If omitted, Traversal generates one automatically.

inputstring required

The incident description or question to investigate. This is the primary context Traversal uses to begin its analysis.

timestring nullable

ISO-8601 timestamp indicating when the incident occurred. Helps Traversal scope its investigation to the relevant time window.

idempotency_keystring required

A unique client-generated key to ensure idempotent session creation. If a session with this key already exists, it is returned instead of creating a duplicate.

thinking_mode'auto' | 'deep' | 'fast'

Investigation depth exposed on the public V1 API.

A deliberately narrower contract than the internal ThinkingMode: the lightning and ultra tiers are reserved for internal surfaces and are not offered here, so unsupported values are rejected at request-parse time rather than at runtime. Values mirror ThinkingMode so the mapping stays in lockstep.

Example request

{
  "title": "Elevated error rate in checkout service",
  "input": "Our checkout service started returning 500 errors at 2024-03-15T14:30:00Z. Error rate jumped from 0.1% to 15%.",
  "time": "2024-03-15T14:30:00Z",
  "idempotency_key": "pagerduty-incident-P12345"
}

Response

Successful Response

idstring required

Unique identifier for the session.

statusstring required

Current lifecycle state of the session. One of: running (investigation in progress), idle (investigation complete, ready for follow-ups), follow_up_running (processing a follow-up message), cancelled, or failed.

titlestring nullable

Human-readable session title. Set via the title field on creation, or auto-generated by Traversal.

inputstring required

The original incident description or question that initiated this session.

created_atstring date-time required

Timestamp when the session was created, in UTC.

updated_atstring date-time nullable

Timestamp when the session was last updated, in UTC. Null if the session has not been updated since creation.

Example response

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "status": "running",
  "messages": [
    {
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "confidence": "Medium",
      "confidence_explanation": "The evidence suggests a likely cause, but alternative explanations cannot be ruled out."
    }
  ]
}

Changes

  • 6ee9e975dda2Revision changes
    • info

      added the non-success response with the status

    • info

      removed the non-success response with the status