> ## Documentation Index > Fetch the complete documentation index at: https://docs.apostra.com/llms.txt > Use this file to discover all available pages before exploring further. # Request a text-message line for an Agent > Buy one SMS-capable US number and bind it to one active storefront Agent. Only a signed-in Seller Account administrator may call it: API keys, M2M clients, service tokens, impersonated or simulated sessions, and Apostra staff support access are refused, because the request buys a number from a carrier. A 202 response means the request was saved, not that a number was bought; poll the request to follow it. The price fields limit the carrier's quote, re-read immediately before the order; the carrier offers no maximum-price field on a number order. ## OpenAPI ````yaml /v2/storefront-api-v2.yaml post /communications/phone-lines openapi: 3.0.0 info: title: Scope3 Storefront API version: 2.0.0 description: >- REST API for partners to manage Seller Accounts, inventory sources, and billing. ## Authentication All endpoints require a Bearer token in the Authorization header: ``` Authorization: Bearer your-api-key ``` ## Base URL `https://api.apostra.com/api/v2/storefront` ## For AI Agents AI agents can use the MCP endpoint at `/mcp/v2/storefront` with three tools: - `initialize`: Start an MCP session - `api_call`: Make REST API calls - `ask_about_capability`: Learn about API features servers: - url: https://api.apostra.com/api/v2/storefront description: Production server security: [] tags: - name: Account description: Account management, service tokens, and preferences - name: Asks description: >- What you are waiting on Scope3 for — support, product, and supply asks in one list - name: Storefront description: Manage storefront and inventory sources - name: Storefront Agents description: List and manage registered sales, signals, and outcomes agents - name: Storefront Activity description: Audit log of configuration and inventory changes on the storefront - name: Storefront Billing description: Payout bank details and billing configuration for Seller Accounts - name: AI Usage description: Seller Account AI token usage visibility by model - name: MCP description: Model Context Protocol endpoints paths: /communications/phone-lines: servers: - url: /api/v2 description: Shared customer API base URL post: tags: - Communications summary: Request a text-message line for an Agent description: >- Buy one SMS-capable US number and bind it to one active storefront Agent. Only a signed-in Seller Account administrator may call it: API keys, M2M clients, service tokens, impersonated or simulated sessions, and Apostra staff support access are refused, because the request buys a number from a carrier. A 202 response means the request was saved, not that a number was bought; poll the request to follow it. The price fields limit the carrier's quote, re-read immediately before the order; the carrier offers no maximum-price field on a number order. operationId: provisionAgentPhoneLine requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/ProvisionAgentPhoneLineBody' responses: '202': description: Request a text-message line for an Agent content: application/json: schema: $ref: '#/components/schemas/ProvisionAgentPhoneLineResponse' '400': description: Bad request content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '403': description: >- The credential lacks `interchange:admin`, or the caller is not a directly authenticated Seller Account administrator. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '404': description: Agent phone lines are not enabled. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '409': description: >- The request ID was reused with different input, or this Agent already has a line or an unresolved request. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: Internal server error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' security: - bearerAuth: [] components: schemas: ProvisionAgentPhoneLineBody: type: object properties: requestId: type: string format: uuid pattern: >- ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$ description: >- Idempotency UUID for this intended line. Replaying it with the same body returns the original request instead of buying a second number. storefrontAgentId: type: string minLength: 1 maxLength: 200 description: Active storefront Agent that will own the line. areaCode: type: string pattern: ^[2-9]\d{2}$ description: US area code to buy the number in. maxQuotedUpfrontUsdCents: type: integer minimum: 0 maximum: 10000 description: >- Highest upfront price accepted from the carrier's own quote for the exact number, re-read immediately before the order. The carrier offers no maximum-price field on a number order, so this is not a carrier-enforced cap. maxQuotedMonthlyUsdCents: type: integer minimum: 0 maximum: 10000 description: >- Highest recurring price accepted from the carrier's own quote for the exact number, re-read immediately before the order. The carrier offers no maximum-price field on a number order, so this is not a carrier-enforced cap. required: - requestId - storefrontAgentId - areaCode - maxQuotedUpfrontUsdCents - maxQuotedMonthlyUsdCents ProvisionAgentPhoneLineResponse: type: object properties: data: type: object properties: provisioning: type: object properties: requestId: type: string format: uuid pattern: >- ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$ storefrontAgentId: type: string areaCode: type: string status: type: string enum: - requested - ordering - order_pending - binding - active - failed - submission_unknown description: >- Durable workflow state. `submission_unknown` is terminal: the carrier may hold an order Apostra could not confirm, an operator reconciles it, and it never retries. phoneNumber: nullable: true description: Assigned number in E.164 format once one is held. type: string endpointId: nullable: true description: Agent text-line ID once the line is active. type: string quotedUpfrontUsdMicros: nullable: true description: >- Upfront price accepted from the carrier quote, in USD micros (1,000,000 micros = 1 USD). type: integer minimum: 0 maximum: 9007199254740991 quotedMonthlyUsdMicros: nullable: true description: >- Recurring price accepted from the carrier quote, in USD micros (1,000,000 micros = 1 USD). type: integer minimum: 0 maximum: 9007199254740991 failureCode: nullable: true description: Bounded reason the request stopped, when it stopped. type: string duplicate: type: boolean description: >- True when this response replays an earlier identical request. required: - requestId - storefrontAgentId - areaCode - status - phoneNumber - endpointId - quotedUpfrontUsdMicros - quotedMonthlyUsdMicros - failureCode - duplicate additionalProperties: false required: - provisioning additionalProperties: false error: type: string nullable: true enum: - null required: - data - error additionalProperties: false ErrorResponse: type: object properties: data: type: string nullable: true enum: - null error: $ref: '#/components/schemas/ApiError' required: - data - error additionalProperties: false description: Standard error response ApiError: type: object properties: code: type: string description: Machine-readable error code message: type: string description: Human-readable error message field: description: Field path associated with the error type: string details: description: Additional error context type: object additionalProperties: {} required: - code - message additionalProperties: false description: Structured error object securitySchemes: bearerAuth: type: http scheme: bearer description: API key or access token ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.