API quickstart

API quickstart

This is the shortest path from zero to a working integration. You’ll upload a log file, poll until analysis is ready, fetch the finished dashboard, and run a search, all with curl against the public /api/v1 surface.

Before you start: you need an API key. See Getting API access to qualify, then Authentication & API keys to create one. Every request below uses the header Authorization: API_KEY <your-key>, not Bearer.

Set your key once for the snippets below:

export LOGCAT_API_KEY="your-api-key-here"
export API="https://api.logcat.ai/api/v1"

1. Upload a file

Upload is a multipart POST. The id in the response is the file ID you’ll poll on.

curl -X POST "$API/upload" \
  -H "Authorization: API_KEY $LOGCAT_API_KEY" \
  -F "file=@bugreport-2026-07-03.zip"

{
  "code": 201,
  "message": "File uploaded successfully",
  "data": {
    "id": "a1b2c3d4-...",
    "name": "bugreport-2026-07-03.zip",
    "file_type": "bugreport",
    "status": "INDEXING"
  }
}

Formats are auto-detected at ingest, so you don’t label the file type. See Supported file types for what’s accepted.

2. Poll for completion

Analysis is asynchronous. Poll the file’s status until it reaches a terminal state.

curl "$API/files/a1b2c3d4-..." \
  -H "Authorization: API_KEY $LOGCAT_API_KEY"

The status walks through INDEXING, ANALYZING, VISUALIZING, COMPLETED. Wait for COMPLETED. It’s the only ready signal: at VISUALIZING the results aren’t finished yet. See Analysis lifecycle & polling for every status and how to handle a failure.

A simple poll loop:

while :; do
  file=$(curl -s "$API/files/a1b2c3d4-..." \
    -H "Authorization: API_KEY $LOGCAT_API_KEY")
  status=$(echo "$file" | jq -r '.data.status')
  echo "status: $status"
  [ "$status" = "COMPLETED" ] && break
  # A FAILED file with can_retry=true may still recover on its own, so keep polling.
  if [ "$status" = "FAILED" ] && [ "$(echo "$file" | jq -r '.data.can_retry')" = "false" ]; then
    echo "analysis failed permanently"; break
  fi
  sleep 5
done

3. Fetch the dashboard

Once the file is COMPLETED, pull the finished analysis dashboard: its chart spec plus the data behind it.

curl "$API/files/a1b2c3d4-.../dashboard" \
  -H "Authorization: API_KEY $LOGCAT_API_KEY"

4. Search the file

Ask questions against the analyzed file. Quick is a single-pass answer in seconds; deep runs a multi-step investigation.

# Quick search: fast, single-pass
curl -X POST "$API/files/a1b2c3d4-.../searches/quick" \
  -H "Authorization: API_KEY $LOGCAT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "Why did com.example.app crash?"}'

# Deep research: multi-step, root-cause investigation
curl -X POST "$API/files/a1b2c3d4-.../searches/deep" \
  -H "Authorization: API_KEY $LOGCAT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "Why did this device reboot during video playback?"}'

For live, streamed search results (step-by-step progress and token-by-token answers), connect over WebSocket instead. See WebSocket streaming.

What next