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

> ## Agent Instructions
> Use Stable documentation by default. Honor an explicit Beta request or a URL under /docs/beta/. If the requested version conflicts with the installed CLI package or API origin, clarify the target before writing integration code.
> Pages under /docs/beta/ document Beta; other product pages document Stable. Keep the CLI package, commands, API origin, and credentials within the selected version. State the documentation version in your answer.
> For MCP search, always pass version: Stable or version: Beta. Unfiltered search mixes both versions. For filesystem reads, keep Beta queries under /beta/ and exclude /beta/ from Stable queries; discover paths before reading them.
> The public docs base is https://photon.codes/docs. Convert MCP page paths to public URLs under that base, preserving /beta/ when present. Read https://photon.codes/docs/skill.md for version selection and https://photon.codes/docs/llms.txt for the version indexes.

# Provision dedicated iMessage line

> Provision dedicated iMessage line: provisionImessageDedicatedLine in the TypeScript, Python and Rust clients.

`POST /v1/projects/{id}/platforms/imessage/dedicated`

Claims one dedicated iMessage line for the project and enables iMessage on it. Always answers 202 with an operation: dedicated lines are allocated from available capacity, and unavailable capacity causes a wait rather than a failure — this can legitimately stay `running` for hours, which is exactly why the response is a handle to poll rather than a number. The project's messaging subscription must grant the dedicated iMessage lines entitlement (`imessage_dedicated_lines.can_purchase`), and that is checked before capacity is reserved. The line's own charge starts when a line is claimed; the subscription that grants the entitlement bills on its own terms, which cancelling a request does not change. Waiting requests are served first come, first served. One that is still waiting is cancelled with a `reason` if the project is deleted (`project_deleted`) or its plan stops selling dedicated lines (`entitlement_lost`); while the payer is restricted for overdue payment it keeps waiting. If you no longer want to wait, POST to the operation's cancel endpoint, which charges nothing for the line. The Idempotency-Key is required and permanent: repeating it returns the same operation forever. A further line always needs a NEW key, including while others are still waiting. Requires the platforms:write permission bound to the project resource in the path.

<Tabs>
  <Tab title="TypeScript">
    ```typescript TypeScript theme={null}
    photon.projects.platforms.provisionImessageDedicatedLine(input: ProvisionImessageDedicatedLineInput, options?: RequestOptions): Promise<ProvisionImessageDedicatedLineOutput>
    ```
  </Tab>

  <Tab title="Python">
    ```python Python theme={null}
    photon.projects.platforms.provision_imessage_dedicated_line(input: ProvisionImessageDedicatedLineInput) -> models.Operation
    ```
  </Tab>

  <Tab title="Rust">
    ```rust Rust theme={null}
    client.provision_imessage_dedicated_line(idempotency_key: String, id: String).await -> Result<ResponseValue<types::Operation>, Error<ProvisionImessageDedicatedLineError>>
    ```
  </Tab>
</Tabs>

<RequestExample>
  ```typescript TypeScript theme={null}
  import { Photon } from "@photon-ai/api";

  const photon = new Photon({
    headers: { Authorization: `Bearer ${process.env.PHOTON_API_TOKEN}` },
  });
  const result = await photon.projects.platforms.provisionImessageDedicatedLine({
    path: {
      id: "id",
    },
    headers: {
      idempotencyKey: "idempotencyKey",
    },
  });
  ```

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

  from photon_api import Photon
  from photon_api.rpc_generated import ProvisionImessageDedicatedLineInput

  photon = Photon(headers={"Authorization": f"Bearer {os.environ['PHOTON_API_TOKEN']}"})
  result = photon.projects.platforms.provision_imessage_dedicated_line(
      ProvisionImessageDedicatedLineInput.model_validate({
          "path": {
              "id": "id",
          },
          "headers": {
              "Idempotency-Key": "idempotencyKey",
          },
      })
  )
  ```

  ```rust Rust theme={null}
  use photon_ai_api::{Credential, PhotonClientBuilder, SecretString};

  let token = std::env::var("PHOTON_API_TOKEN")?;
  let client = PhotonClientBuilder::new()
      .credential("accountServiceKey", Credential::Bearer(SecretString::from(token)))
      .build()?;
  let result = client
      .provision_imessage_dedicated_line("idempotencyKey".to_owned(), "id".to_owned())
      .await
      .map_err(|error| format!("{error:?}"))?
      .into_inner();
  ```
</RequestExample>

<ResponseExample>
  ```json 202 theme={null}
  {
    "cancellable": true,
    "createdAt": "2026-01-01T00:00:00.000Z",
    "detail": {},
    "endedAt": "2026-01-01T00:00:00.000Z",
    "error": {
      "code": "string",
      "detail": "string"
    },
    "operationId": "string",
    "projectId": "string",
    "reason": "charge_refused",
    "resourceId": "string",
    "resourceType": "string",
    "startedAt": "2026-01-01T00:00:00.000Z",
    "state": "pending",
    "type": "resource.provision",
    "updatedAt": "2026-01-01T00:00:00.000Z"
  }
  ```
</ResponseExample>

## Parameters

<ParamField header="Idempotency-Key" type={"string"} required>
  Identifies one logical mutation across retries.
</ParamField>

<ParamField path="id" type={"string"} required />

## Returns

**`202`** The provision was accepted and is running. GET the Location after the Retry-After interval until `state` is terminal; the response there carries the line once one is claimed. Operation

Headers: `Location`. The raw response carries these headers; see [Raw responses](/docs/beta/api-client/raw-responses).

<ResponseField name="cancellable" type={"boolean"} required />

<ResponseField name="createdAt" type={"string (date-time)"} required />

<ResponseField name="detail" type={"object"} />

<ResponseField name="endedAt" type={"string (date-time)"} />

<ResponseField name="error" type={"OperationError"} />

<ResponseField name="operationId" type={"string"} required />

<ResponseField name="projectId" type={"string"} required />

<ResponseField name="reason" type={"OperationReason"} />

<ResponseField name="resourceId" type={"string"} />

<ResponseField name="resourceType" type={"string"} required />

<ResponseField name="startedAt" type={"string (date-time)"} />

<ResponseField name="state" type={"OperationState"} required />

<ResponseField name="type" type={"OperationType"} required />

<ResponseField name="updatedAt" type={"string (date-time)"} required />


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.