Developers & API

Build agents on Socrates.

Everything an automated client needs: a typed OpenAPI surface, OAuth 2.0 with PKCE, scoped long-lived agent keys, an MCP server, and machine-readable discovery at predictable URLs.

View OpenAPI Spec Auth Guide

Quickstart

Three steps to your first agent call.

STEP 01

Pick an auth route

Third-party agents use the OAuth 2.0 authorization-code flow with PKCE. First-party automation mints a scoped key in the app or via the API.

Authorization: Bearer ak_<keyId>.<secret>

STEP 02

Read the contract

Every public endpoint is specified in the OpenAPI 3.0 specification — operationIds, request/response schemas, error codes, and per-operation OAuth scopes.

curl -s https://topodrive.top/openapi.json

STEP 03

Call the API

Base URL https://app.topodrive.top. Health probe first: GET /api/v2/health. Rate-limit headers (RateLimit-Limit / -Remaining / -Reset) ride every response.

GET https://app.topodrive.top/api/v2/health

Machine-readable endpoints

Discovery index.

Socrates advertises machine-readable contracts and manifests at standardized URLs for agent crawlers, developer toolchains, and LLMs.

Resource	Endpoint	Format
OpenAPI specification	/openapi.json	openapi+json
Authentication reference	/auth.md	markdown
Protected-resource metadata (RFC 9728)	/.well-known/oauth-protected-resource	json
Authorization-server metadata (RFC 8414)	/.well-known/oauth-authorization-server	json
MCP server (Streamable HTTP, read-only tools)	app.topodrive.top/api/mcp	json-rpc 2.0
MCP server card	/.well-known/mcp/server-card.json	json
A2A agent card	/.well-known/agent-card.json	json
Agent skills index (v0.2.0)	/.well-known/agent-skills/index.json	json
Skill package (agentskills format)	/SKILL.md	markdown
API catalog (RFC 9727 linkset)	/.well-known/api-catalog	linkset+json
Navigation index for LLMs	/llms.txt · /llms-full.txt	plain text

Architecture & Rules

What every endpoint has in common.

Typed errors

Failures return one shape: {"code": "MACHINE_READABLE_CODE", "message": "human detail", "detail": …} with standard HTTP statuses: 400 validation, 401 UNAUTHORIZED, 403 INSUFFICIENT_SCOPE, 404 NOT_FOUND, 429 TOO_MANY_REQUESTS.

Scoped grants

OAuth tokens and agent keys carry grants from a closed set (chat:read/write, sessions:…, memory:…, files:…, projects:…). Read methods demand :read, mutations demand :write.

Idempotency

Send Idempotency-Key: <uuid> on any write; replays within 24 hours return the original response instead of duplicating work.

Rate limits

Standard RateLimit-Limit, RateLimit-Remaining, and RateLimit-Reset headers are returned on every request for client-side proactive throttling.

Cursor pagination

List endpoints respond with {items, cursor, hasMore}. Pass ?cursor=<cursor> until hasMore returns false.

Predictable versioning

Deprecations are announced with a Sunset header (HTTP date) and notes in announcements at least 90 days before removal.

Integration Support

Questions while integrating?

Email help@addtech.site — include your request ID (the X-Request-Id response header) and we can trace the exact execution call.