API Reference

API Reference

This page documents the API endpoints provided by the LangGraph Deployment Kit service.

Base URL

All API URLs are relative to your service host, which defaults to:

http://0.0.0.0:8080

You can configure the host and port in your .env file.

Authentication

If AUTH_SECRET is set in your .env file, all API endpoints will require authentication using a Bearer token:

Authorization: Bearer your-auth-secret

Endpoints

Health Check

GET /health

Returns the service status. No authentication required, even if AUTH_SECRET is set.

Response:

{
  "status": "ok"
}

Service Info

GET /info

Returns metadata about the available agents.

Response:

{
  "agents": [
    {
      "key": "research-assistant",
      "description": "A research assistant with web search and calculator."
    }
  ],
  "default_agent": "research-assistant"
}

Invoke Agent

POST /invoke

or

POST /{agent_id}/invoke

Invokes an agent with user input and returns a response.

Request body:

{
  "message": "What is the weather in Tokyo?",
  "model": "gpt-4",
  "thread_id": "optional-thread-id",
  "user_id": "optional-user-id",
  "agent_config": {
    "temperature": 0.7
  }
}

Response:

{
  "type": "ai",
  "content": "The weather in Tokyo is currently 70°F and sunny.",
  "run_id": "847c6285-8fc9-4560-a83f-4e6285809254"
}

Stream Response

POST /stream

or

POST /{agent_id}/stream

Streams an agent's response as a Server-Sent Events (SSE) stream.

Request body:

{
  "message": "What is the weather in Tokyo?",
  "model": "gpt-4",
  "thread_id": "optional-thread-id",
  "user_id": "optional-user-id",
  "stream_tokens": true,
  "stream_node_updates": true,
  "agent_config": {
    "temperature": 0.7
  }
}

Response: A stream of SSE events with the following types:

• token: Individual tokens from the LLM
• message: Complete messages from agents
• node_update: Updates from agent nodes
• error: Error messages

Example stream:

data: {"type": "token", "content": "The"}
data: {"type": "token", "content": " weather"}
data: {"type": "token", "content": " in"}
data: {"type": "token", "content": " Tokyo"}
data: {"type": "node_update", "content": {"node": "chatbot", "updates": {...}}}
data: {"type": "message", "content": {"type": "ai", "content": "The weather in Tokyo is currently 70°F and sunny."}}
data: [DONE]

Submit Feedback

POST /feedback

Records feedback for a previous interaction using Langfuse.

Request body:

{
  "run_id": "847c6285-8fc9-4560-a83f-4e6285809254",
  "key": "human-feedback-stars",
  "score": 0.8,
  "kwargs": {
    "comment": "Very helpful response!"
  }
}

Response:

{
  "status": "success"
}

Get Chat History

POST /history

Retrieves the conversation history for a thread.

Request body:

{
  "thread_id": "847c6285-8fc9-4560-a83f-4e6285809254"
}

Response:

{
  "messages": [
    {
      "type": "human",
      "content": "What is the weather in Tokyo?"
    },
    {
      "type": "ai",
      "content": "The weather in Tokyo is currently 70°F and sunny."
    }
  ]
}