# Add personal vocabulary

Add or enrich up to 100 words directly in the current user's personal vocabulary book while recording their source.

- Capability ID: `vocabulary.personal.add`
- Operation: `ielts_vocabulary_personal_add`
- Category: 词汇
- Endpoint: `POST /api/v1/agent/capabilities/ielts_vocabulary_personal_add`
- Authentication: Bearer Token（通过 /api/v1/agent-bindings 绑定账号）
- Required scopes: vocabulary:write
- Side effect: write
- Human documentation: https://ieltsbuddy.igopx.cn/developers/api/ielts_vocabulary_personal_add

## Request parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `context` | string | 否 | Optional source sentence or context. |
| `items` | record[] | 是 | items |
| `items.example` | string | 否 | Example sentence. |
| `items.expansion` | unknown[] | 否 | Synonyms, collocations, or related expressions. |
| `items.meaning` | string | 否 | Chinese or English meaning. |
| `items.partOfSpeech` | string | 否 | Part of speech. |
| `items.phrase` | string | 是 | Word or phrase. |
| `items.usage` | string | 否 | Usage note. |
| `sourceId` | string | 否 | Stable source record id when available. |
| `sourceTitle` | string | 否 | Human-readable source title. |
| `sourceType` | string | 否 | Origin such as agent, reading_lexicon, practice, or course. |

## Request example

```bash
curl -X POST \
  'https://work.ieltsbuddy.igopx.cn/api/v1/agent/capabilities/ielts_vocabulary_personal_add' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer $IELTS_BUDDY_TOKEN' \
  --data '{"context":"","items":[],"sourceId":"","sourceTitle":"","sourceType":"agent"}'
```

## Request schema

```json
{
  "type": "object",
  "properties": {
    "context": {
      "default": "",
      "description": "Optional source sentence or context.",
      "type": "string"
    },
    "items": {
      "minItems": 1,
      "maxItems": 100,
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "example": {
            "default": "",
            "description": "Example sentence.",
            "type": "string"
          },
          "expansion": {
            "default": [],
            "description": "Synonyms, collocations, or related expressions.",
            "maxItems": 30,
            "type": "array",
            "items": {
              "type": "string",
              "minLength": 1
            }
          },
          "meaning": {
            "default": "",
            "description": "Chinese or English meaning.",
            "type": "string"
          },
          "partOfSpeech": {
            "default": "",
            "description": "Part of speech.",
            "type": "string"
          },
          "phrase": {
            "type": "string",
            "minLength": 1,
            "maxLength": 300,
            "description": "Word or phrase."
          },
          "usage": {
            "default": "",
            "description": "Usage note.",
            "type": "string"
          }
        },
        "required": [
          "example",
          "expansion",
          "meaning",
          "partOfSpeech",
          "phrase",
          "usage"
        ],
        "additionalProperties": false
      }
    },
    "sourceId": {
      "default": "",
      "description": "Stable source record id when available.",
      "type": "string"
    },
    "sourceTitle": {
      "default": "",
      "description": "Human-readable source title.",
      "type": "string"
    },
    "sourceType": {
      "default": "agent",
      "description": "Origin such as agent, reading_lexicon, practice, or course.",
      "type": "string",
      "minLength": 1,
      "maxLength": 80
    }
  },
  "required": [
    "context",
    "items",
    "sourceId",
    "sourceTitle",
    "sourceType"
  ],
  "additionalProperties": false
}
```

## Response envelope

```json
{
  "code": 0,
  "data": {},
  "message": "ok"
}
```

## Errors

| HTTP | Code | Meaning |
| --- | --- | --- |
| 400 | `40001` | 请求参数不符合接口契约 |
| 401 | `40101` | 缺少或使用了无效的访问令牌 |
| 403 | `40301` | 访问令牌不包含接口所需权限 |
| 404 | `40401` | 接口或目标资源不存在 |