API Overview - SoCMate

The SoCMate API provides programmatic access to investigations, incidents, the knowledge graph, search, and platform administration. All endpoints return JSON and follow REST conventions.

Base URL

All API requests are made against your organization’s SoCMate API endpoint:

https://api.socmate.yourcompany.com

Authentication

SoCMate supports two authentication methods:

API Key
OAuth2 / JWT
OAuth2 Client Credentials

For machine-to-machine integrations, use an API key in the X-API-Key header. API keys are created by admins in the Admin panel.

curl -X GET https://api.socmate.yourcompany.com/api/v1/search?q=phishing \
  -H "X-API-Key: sk_live_abc123..."

API keys are scoped to specific permissions (e.g., investigations:read, incidents:read). See API Keys for details.

For user-facing applications, use the OAuth2 Authorization Code flow to obtain a JWT access token, then pass it as a Bearer token.

curl -X GET https://api.socmate.yourcompany.com/api/v1/search?q=phishing \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIs..."

See Authentication for the full OAuth2 flow.

For service-to-service integrations, use the OAuth2 Client Credentials flow to obtain a JWT token from the authentication endpoint.

# Step 1: Get access token
curl -X POST https://auth.socmate.yourcompany.com/oauth/token \
  -d "grant_type=client_credentials" \
  -d "client_id=your-client-id" \
  -d "client_secret=your-client-secret"

# Step 2: Use the token
curl -X GET https://api.socmate.yourcompany.com/api/v1/search?q=phishing \
  -H "Authorization: Bearer <access_token>"

See API Clients for creating OAuth2 clients.

Rate Limits

Authentication Method	Rate Limit
API Key	Per-key limits configured at creation
OAuth2 JWT (user)	100 requests/minute per user
OAuth2 Client Credentials	200 requests/minute per client
Concurrent investigations	Configurable per deployment (default: 5 per user)

When a rate limit is exceeded, the API returns 429 Too Many Requests with a Retry-After header.

Error Format

All error responses follow a consistent format:

{
  "detail": "Human-readable error message describing what went wrong"
}

For validation errors (422), the response includes field-level details:

{
  "detail": [
    {
      "loc": ["body", "query"],
      "msg": "field required",
      "type": "value_error.missing"
    }
  ]
}

Status Codes

Code	Meaning
`200`	Success
`201`	Resource created
`204`	Success (no content)
`400`	Bad request — invalid parameters
`401`	Unauthorized — missing or invalid token
`403`	Forbidden — insufficient permissions or role
`404`	Resource not found
`409`	Conflict — duplicate resource or invalid state transition
`422`	Validation error — request body failed validation
`429`	Too many requests — rate limit or concurrent session limit exceeded
`500`	Internal server error
`502`	Bad gateway — upstream service error
`503`	Service unavailable — dependency down (e.g., Sentinel)

Pagination

List endpoints support cursor-based pagination with offset and limit parameters:

curl -X GET "https://api.socmate.yourcompany.com/api/v1/sessions/?limit=20&offset=40" \
  -H "X-API-Key: sk_live_abc123..."

Paginated responses include total count:

{
  "sessions": [...],
  "total": 142,
  "limit": 20,
  "offset": 40
}

Parameter	Type	Default	Description
`limit`	integer	`20`	Maximum number of items to return (max 100)
`offset`	integer	`0`	Number of items to skip

Common Headers

Header	Required	Description
`Authorization`	Yes (if not using API key)	`Bearer <jwt_token>`
`X-API-Key`	Yes (if not using JWT)	API key value
`Content-Type`	Yes (for POST/PATCH/PUT)	`application/json`
`Accept`	Optional	`application/json` (default) or `text/event-stream` (for SSE)

API Sections

Authentication

OAuth2 flow, API key usage, token refresh, and JWT structure.

Investigations

Start investigations, send follow-ups, stream results, and query sessions.

Incidents

List, enrich, and manage Sentinel incidents.

Knowledge Graph

Query entity neighborhoods, investigation subgraphs, and entity search.

​Base URL

​Authentication

​Rate Limits

​Error Format

​Status Codes

​Pagination

​Common Headers

​API Sections

Authentication

Investigations

Incidents

Knowledge Graph

Base URL

Authentication

Rate Limits

Error Format

Status Codes

Pagination

Common Headers

API Sections