Pod API

The Pod (SUMARiS server application) exposes several APIs, all served by the same server:

API	Endpoint	Usage
Online documentation	<PEER_URL>/api	Home page of the Pod documentation and tools
GraphQL	<PEER_URL>/graphql	Data access (read/write), used by the App
GraphQL (subscriptions)	<PEER_URL>/graphql/websocket	Real-time notifications (WebSocket)
REST	<PEER_URL>/api/...	Referentials, extractions, node information, images...
MCP server	<PEER_URL>/api/mcp	Business tools for AI assistants (Claude, ChatGPT, Mistral...)
OpenAI-compatible chat	<PEER_URL>/api/v1	LLM proxy using the Pod business tools

<PEER_URL> is the address of the Pod, e.g. http://localhost:8080 for a local Pod (see Pod: setup). In the examples below, it is read from an environment variable:

export PEER_URL="http://localhost:8080"

Pod online documentation

Every Pod publishes its own documentation, always matching its version, at <PEER_URL>/api:

Page	Address	Content
Home	<PEER_URL>/api	Links to the documentation and tools below
Swagger UI	<PEER_URL>/api/swagger-ui	REST endpoints, with request execution from the browser
OpenAPI definition	<PEER_URL>/v3/api-docs	OpenAPI 3 description (JSON) of the REST API, to generate a client
GraphiQL	<PEER_URL>/api/graphiql	GraphQL query editor, with auto-completion and schema documentation
GraphQL subscriptions	<PEER_URL>/graphql/websocket/test	Subscription query editor (WebSocket)
AI features	<PEER_URL>/api/ai	MCP server and chat API: client configuration, list of tools
Extraction documentation	<PEER_URL>/api/extraction/doc	Extraction formats available on the Pod

The shortcuts <PEER_URL>/api/docs and <PEER_URL>/swagger-ui.html redirect to Swagger UI.

Authentication

Public data (referentials) can be read anonymously. Other data requires authentication, with the same rights as the user in the App.

For a script or an external tool, the simplest way is a personal API token:

1. log in to the App connected to the Pod;
2. open the My account > Tokens page and create a token;
3. copy its value (displayed only once) into an environment variable, never into a committed file:

export SUMARIS_API_KEY="<token value>"

The token is sent in the HTTP Authorization header, in one of these forms:

• Authorization: Bearer <token>: standard format, used by MCP clients and OpenAI libraries;
• Authorization: token <token>: format used by the App.

A token can be revoked at any time from the same My account > Tokens page.

GraphQL API

GraphQL is the main API of the Pod: the App uses it for all its data reads and writes.

• Endpoint: POST <PEER_URL>/graphql (JSON body {"query": "...", "variables": {...}});
• Full schema (SDL): GET <PEER_URL>/graphql/schema;
• Interactive editor: <PEER_URL>/api/graphiql (the Docs tab browses queries and types).

Example, anonymous read of a referential (countries):

curl "$PEER_URL/graphql" \
  -H "Content-Type: application/json" \
  -d '{"query": "{ referentials(entityName: \"Location\", filter: {levelIds: [1]}, size: 2) { id label name } }"}'
# => {"data":{"referentials":[{"id":3,"label":"BEL","name":"Belgium"},{"id":1,"label":"FRA","name":"France"}]}}

Example, authenticated query:

curl "$PEER_URL/graphql" \
  -H "Authorization: Bearer $SUMARIS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "{ account { id firstName lastName } }"}'

The referential entities that can be queried are listed by { referentialTypes { id } }.

Subscriptions (WebSocket)

GraphQL subscriptions notify the App of changes (data updates, new messages, job progress...). They use a WebSocket connection on <PEER_URL>/graphql/websocket. The page <PEER_URL>/graphql/websocket/test can be used to test a subscription query.

REST API

The REST API complements GraphQL for simpler use cases and file downloads. Its reference documentation is Swagger UI (<PEER_URL>/api/swagger-ui), generated from the Pod code, with the matching OpenAPI definition (<PEER_URL>/v3/api-docs).

Main groups of endpoints:

Path	Usage
/api/node/info	Pod name and version
/api/node/health	Health of the Pod and its components (database, AI...)
/api/referential/...	List of referential types, search in a referential
/api/extraction/...	Extraction types, extraction downloads, format documentation
/api/feed	Pod news feed (JSON Feed)
/api/image/..., /api/avatar/..., /api/logo/...	Images (photos, avatars, logos)

Examples:

# Pod version
curl "$PEER_URL/api/node/info"

# Referential types, then search for locations
curl "$PEER_URL/api/referential/list"
curl "$PEER_URL/api/referential/Location/search?size=2"

# Available extraction types
curl "$PEER_URL/api/extraction/types"

MCP server (AI assistants)

The Pod is an MCP server (Model Context Protocol): an AI assistant (Claude, ChatGPT, Mistral, Copilot, local LLM...) can connect to it and call the Pod business tools by itself.

• Endpoint: <PEER_URL>/api/mcp, Streamable HTTP transport;
• Without a token: only the public referential tools are usable (species, gears, locations, units...);
• With a token: tools on programs, strategies, trips and the user profile are also usable, restricted to the user's rights.

The page <PEER_URL>/api/ai lists the tools actually available on the Pod. For reference:

Domain	Tools
Referentials	ref_search_species, ref_search_referential, ref_list_programs, ref_get_program
Programs	program_search, program_get, program_save
Strategies	strategy_search, strategy_get, strategy_save
Trips	trip_search, trip_get
User	person_me (checks the token and identifies the user)

Example, adding the server to Claude Code:

claude mcp add --transport http sumaris "$PEER_URL/api/mcp" \
  --header "Authorization: Bearer $SUMARIS_API_KEY"

Example, JSON configuration (Claude Code .mcp.json, Cursor, Windsurf...):

{
  "mcpServers": {
    "sumaris": {
      "type": "http",
      "url": "<PEER_URL>/api/mcp",
      "headers": {
        "Authorization": "Bearer ${SUMARIS_API_KEY}"
      }
    }
  }
}

The MCP server is enabled by the Pod option spring.ai.mcp.server.enabled. The page <PEER_URL>/api/ai also covers clients supporting only local servers (mcp-remote bridge) and a prompt example to connect an assistant.

OpenAI-compatible chat API

The Pod can also act as an LLM proxy, compatible with the OpenAI Chat Completions API. The LLM provider (and its key) is configured on the Pod: the client only needs its SUMARiS token. The LLM can call the same business tools as the MCP server, with the user's rights.

OpenAI client setting	Value
Base URL	<PEER_URL>/api/v1
API key	the SUMARiS token (SUMARIS_API_KEY)
Model	a model listed by GET <PEER_URL>/api/v1/models, or default

curl "$PEER_URL/api/v1/chat/completions" \
  -H "Authorization: Bearer $SUMARIS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "default", "messages": [{"role": "user", "content": "Which data collection programs can I access?"}]}'

Limitations: only POST /api/v1/chat/completions and GET /api/v1/models are available, without streaming. The API is enabled by the option sumaris.ai.chat.enabled (Pod options sumaris.ai.chat.*). See <PEER_URL>/api/ai for attached files, conversations and error codes.