Agent Discovery & Machine-Friendly Endpoint Access

# Agent Discovery & Machine-Friendly Endpoint Access

This page is for automation, bots, and AI assistants that need to discover how to call Network Storage safely.

## Machine discovery entrypoints

### Global manifest

`/.well-known/mcp.json`

This public endpoint returns the canonical API surface and runtime hints:

```json
{
  "manifestVersion": 1,
  "discovery": {
    "projectAgentManifest": "https://api.sboxcool.com/v3/manage/{projectId}/agent-manifest",
    "projectEndpointTemplate": "https://api.sboxcool.com/v3/endpoints/{projectId}/{endpointSlug}"
  },
  "auth": {
    "projectAuth": {
      "required": true,
      "header": "x-api-key",
      "query": "apiKey"
    },
    "endpointSecret": {
      "header": "x-secret-key",
      "aliases": ["secretKey", "networkStorageSecret", "network_storage_secret_key"]
    }
  }
}
```

### Project-specific manifest

`GET /v3/manage/{projectId}/agent-manifest`

Requires:
- `x-api-key`

Returns a machine-readable snapshot of endpoints, with optional collections/workflows:

```bash
curl -H "x-api-key: sbox_sk_..." \
  "https://api.sboxcool.com/v3/manage/<projectId>/agent-manifest?includeCollections=true&includeWorkflows=true"
```

Optional query params:

- `includeCollections=true` include collection names/schemas.
- `includeWorkflows=true` include workflow names and params.
- `includeInternal=true` include internal/hidden resources.
- `includeDeprecated=true` include deprecated endpoints.

### Example response (minimum `includeCollections=false&includeWorkflows=false`)

```json
{
  "ok": true,
  "manifestVersion": 1,
  "project": {
    "id": "<projectId>",
    "title": "Project Alpha",
    "enabled": true,
    "visibility": {
      "requireSboxAuth": true,
      "enableAuthSessions": true,
      "requireAuthSessions": false,
      "enableEncryptedRequests": true
    },
    "revision": {
      "currentRevisionId": 12,
      "latestRevisionId": 15,
      "revisionPublishedAt": "2025-01-01T00:00:00.000Z"
    },
    "urls": {
      "endpointManifest": "https://api.sboxcool.com/v3/manage/<projectId>/agent-manifest?includeCollections=false&includeWorkflows=false",
      "endpointTemplate": "https://api.sboxcool.com/v3/endpoints/{projectId}/{endpointSlug}"
    }
  },
  "execution": {
    "routeTemplate": "https://api.sboxcool.com/v3/endpoints/<projectId>/{endpointSlug}",
    "methods": ["GET", "POST"],
    "responsePolicy": {
      "httpStatus": 200,
      "bodyStatusCode": "status",
      "bodyErrorCode": "error"
    }
  },
  "capabilities": {
    "expressionOperators": ["==", "!=", ">", "<", ">=", "<=", "in", "contains"],
    "stepTypes": ["read", "lookup", "transform", "write"],
    "stepTypesObserved": ["read", "lookup", "transform", "write"]
  },
  "endpointAuthHeaders": {
    "projectHeader": "x-api-key",
    "projectQuery": "apiKey",
    "secretHeader": "x-secret-key",
    "steamHeader": "x-steam-id",
    "steamQuery": "steamId",
    "revisionHeader": "x-ns-revision-id",
    "authSessionHeader": "x-auth-session-token",
    "endpointFieldAliases": {
      "endpointSlug": "_endpointSlug",
      "endpoint": "endpoint",
      "bodyEndpointField": "input.endpoint"
    }
  },
  "links": {
    "docs": {
      "agentDiscovery": "/wiki/network-storage-v3/agent-discovery"
    }
  },
  "endpoints": [
    {
      "slug": "report-kill",
      "id": "ep_report_kill",
      "name": "Report Kill",
      "method": "POST",
      "enabled": true,
      "publiclyCallable": true,
      "exposure": "public",
      "requiresSecretKey": false,
      "skipSboxAuth": false,
      "url": "https://api.sboxcool.com/v3/endpoints/<projectId>/report-kill",
      "input": {
        "type": "object",
        "properties": {
          "target_type": { "type": "string" }
        },
        "required": ["target_type"]
      },
      "response": {
        "status": 200,
        "body": {
          "success": true,
          "xp_earned": 0
        }
      }
    }
  ]
}
```

## Minimal call flow for automation

1. Fetch `/.well-known/mcp.json`.
2. Pick one project and call `/v3/manage/{projectId}/agent-manifest`.
3. For each endpoint, read:
   - `method`
   - `slug`
   - `url`
   - `input`
   - `requiresSecretKey`, `skipSboxAuth`
4. Call:
   - `POST https://api.sboxcool.com/v3/endpoints/{projectId}/{endpointSlug}`
   - or `GET` for GET-only endpoints.

## Required headers when calling endpoints

- `x-api-key` (required for all calls)
- `x-steam-id` (required unless the endpoint uses `skipSboxAuth` and no secret fallback)
- `x-secret-key` (required when `requiresSecretKey: true`)
- `x-auth-session-token` or `x-auth-session` (when auth sessions are enabled)
- `x-ns-revision-id` (optional)

### Body pattern

```json
{
  "foo": "value",
  "steamId": "76561198123456789"
}
```

`steamId` is validated by the API and can also be sent as a query parameter.

## Discovery and response shape for endpoint calls

Endpoint responses use the Network Storage runtime contract:

- HTTP status is usually `200`.
- Runtime status code is in the JSON `status` field.
- Request ID is returned as `_requestId`.

Most responses include `_revisionStatus` for client revision alignment.

## Practical runtime expressions reference

Supported operators:

`==`, `!=`, `>`, `<`, `>=`, `<=`, `contains`, `not_contains`, `in`, `not_in`, `exists`, `not_exists`, `starts_with`, `not_starts_with`

Common aliases:

`eq`, `neq`, `ne`, `gt`, `lt`, `gte`, `lte`, `le`, `includes`, `has`, `not_contains`, `not_includes`, `not_has`, `notcontains`, `not_in`, `notin`, `not_exists`, `notexist`, `startswith`, `notstartswith`

Supported math helpers:

`abs`, `ceil`, `clamp`, `dayOfWeek`, `diffMs`, `diffS`, `floor`, `hour`, `log10`, `max`, `min`, `now`, `nowS`, `pow`, `random`, `round`

## Related docs

- [Endpoint Standards](./endpoint-standards)
- [Math and expression behavior](./math-expressions)
- [Revision handling](./revision-handling)