# API Conventions

You will learn: The response structure, path conventions, authentication methods, and Swagger entry point for OpenFlare management and Agent APIs.

Both the OpenFlare management APIs and Agent APIs use JSON.

## Response Structure

Both success and failure should return a clear `message`:

```json
{
  "success": true,
  "message": "",
  "data": {}
}
```

## Path Conventions

| Type | Convention |
| --- | --- |
| Management API | Authenticated by management console Session |
| Agent API | Fixed under `/api/agent/*` |
| Read-only API | Use `GET` |
| Mutation-type API | Use `POST` |

## Authentication

The management console continues to reuse the existing login, role, and Session system.

Official Agent requests uniformly use the node-exclusive `agent_token`; the first access can use the global `discovery_token`. The Agent request header is fixed as:

```http
X-Agent-Token: <token>
```

Full Tokens must not be printed in the logs.

## Swagger

Accessible after logging into the management console:

```text
/swagger/index.html
```

The Swagger files are located in `openflare_server/docs`, generated by `swag init`.