grix-connector/openclaw-plugin/skills/grix-register/references/api-contract.md

Connect local AI coding agents (Claude, Codex, Gemini, Qwen, DeepSeek, Cursor, OpenCode, Pi, OpenHuman, Reasonix) to the Grix scheduling platform. Also serves as an OpenClaw plugin for Grix channel transport.

# API Contract

## Responsibility Boundary

1. `grix-register` is solely responsible for account authentication and cloud `provider_type=3` Agent parameter production.
2. This skill is not responsible for local OpenClaw configuration.
3. Local configuration is handled by `grix-admin`.

## Base

1. Default website: `https://grix.dhf.pub/`
2. Default public Grix API base: `https://grix.dhf.pub/v1`
3. Local development or private deployment can override the base URL.

## Route Mapping

### Agent bootstrap action

| Action | Method | Route | Auth |
|---|---|---|---|
| `create-api-agent` | `POST` | `/agents/create` | `Authorization: Bearer <access_token>` |
| `list-agents` (internal helper) | `GET` | `/agents/list` | `Authorization: Bearer <access_token>` |
| `rotate-api-agent-key` (internal helper) | `POST` | `/agents/:id/api/key/rotate` | `Authorization: Bearer <access_token>` |

## Payloads

### `create-api-agent`

```json
{
  "agent_name": "grix-main",
  "provider_type": 3,
  "is_main": true
}
```

`provider_type=3` means Agent API type.  
The bundled bootstrap flow uses `is_main=true` so the first API agent gets the full initial scope set.

## Reuse flow

When the same-name `provider_type=3` agent already exists, the skill should:

1. read `/agents/list`
2. find the exact-name API agent
3. rotate its key through `/agents/:id/api/key/rotate`
4. reuse the returned `api_endpoint` and fresh `api_key`

## Success Highlights

### `create-api-agent`

The bundled script lifts these fields to the top level:

1. `agent_id`
2. `agent_name`
3. `provider_type`
4. `api_endpoint`
5. `api_key`
6. `api_key_hint`
7. `session_id`

## Common Errors

1. create-agent or rotate-key returns missing `api_endpoint` or `api_key`

## Handoff

After success, do not pass the structured fields directly as `grix_admin`'s typed params; instead assemble them into a `grix_admin.task`:

1. First line: `bind-local`
2. Then include `agent_id`
3. `agent_name`
4. `api_endpoint`
5. `api_key`
6. Add a line `do_not_create_remote_agent=true`