> ## Documentation Index
> Fetch the complete documentation index at: https://api-docs.ollang.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Create Custom Instruction

> Create a new custom translation instruction for your account

Create a custom instruction string (guideline) that can influence how translations are produced for your projects.

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST "https://api-integration.ollang.com/integration/custom-instructions" \
    -H "X-Api-Key: <your-api-key>" \
    -H "Content-Type: application/json" \
    -d '{
      "key": "tone_and_register",
      "value": "Match the formality level of the source. Business emails should remain professional.",
      "description": "Instructions for maintaining appropriate tone and register"
    }'
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch(
    "https://api-integration.ollang.com/integration/custom-instructions",
    {
      method: "POST",
      headers: {
        "X-Api-Key": "<your-api-key>",
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        key: "tone_and_register",
        value:
          "Match the formality level of the source. Business emails should remain professional.",
        description: "Instructions for maintaining appropriate tone and register",
      }),
    }
  );

  const created = await response.json();
  ```

  ```python Python theme={null}
  import requests

  data = {
      "key": "tone_and_register",
      "value": "Match the formality level of the source. Business emails should remain professional.",
      "description": "Instructions for maintaining appropriate tone and register",
  }

  headers = {
      "X-Api-Key": "<your-api-key>",
      "Content-Type": "application/json",
  }

  response = requests.post(
      "https://api-integration.ollang.com/integration/custom-instructions",
      headers=headers,
      json=data,
  )

  created = response.json()
  ```
</RequestExample>

## Authorizations

This endpoint requires API key authentication.

* **Header name**: `X-Api-Key`
* **Header value**: Your API key from the [Ollang dashboard](https://lab.ollang.com)

## Body Parameters

<ParamField body="key" type="string" required>
  Machine-friendly identifier for this instruction (e.g. `tone_and_register`).
</ParamField>

<ParamField body="value" type="string" required>
  The full instruction text.
</ParamField>

<ParamField body="description" type="string" optional>
  Optional longer description of what this instruction controls.
</ParamField>

## Response

Returns the created custom instruction, including `id`, timestamps, and `scopeRefId`. Same shape as [List Custom Instructions](/apis/ollang-api-reference/list-custom-instructions).

<ResponseExample>
  ```json 201 theme={null}
  {
    "id": "507f1f77bcf86cd799439011",
    "key": "tone_and_register",
    "value": "Match the formality level of the source. Business emails should remain professional.",
    "active": true,
    "description": "Instructions for maintaining appropriate tone and register",
    "scopeRefId": "507f1f77bcf86cd799439012",
    "createdAt": "2023-10-05T12:34:56.789Z",
    "updatedAt": "2023-10-05T12:34:56.789Z"
  }
  ```

  ```json 400 theme={null}
  {
    "statusCode": 400,
    "message": ["key should not be empty"]
  }
  ```

  ```json 401 theme={null}
  {
    "error": "Unauthorized",
    "message": "Invalid or missing API key"
  }
  ```
</ResponseExample>