> ## Documentation Index > Fetch the complete documentation index at: https://docs.hyperline.co/llms.txt > Use this file to discover all available pages before exploring further. # Create a custom agent cost item > Price a non-LLM cost item the registry has never heard of — a search API, a vector DB, GPU seconds, a render. The item is priced entirely by its `dimensions` (its token rates are 0). `provider` and `item` must match, verbatim, the `vendor` and `item` your SDK sends on `hyperline.cost({ vendor, item, quantity, unit })` — they are lowercased and trimmed, nothing else — and each `dimensions[].key` must match the `unit` of the call it prices: `cost()` writes the quantity to `usage_extra[unit]` and pricing matches a dimension by that exact key, so a key that does not match prices nothing. Idempotent by design so a seed script can be re-run: an open custom item already standing for that (provider, item) is returned as it is, rates untouched, with a 200 instead of a fresh 201 — edit a rate by deleting the item and creating it again. A (provider, item) pair the global registry already prices is refused: that model has a price, and a negotiated rate for it goes through the overrides endpoint. ## OpenAPI ````yaml post /v1/ai/billing/cost-catalog/items openapi: 3.1.0 info: title: Hyperline API version: 0.0.0 servers: - url: https://api.hyperline.co - url: https://sandbox.api.hyperline.co security: [] paths: /v1/ai/billing/cost-catalog/items: post: tags: - AI > Billing summary: Create a custom agent cost item description: >- Price a non-LLM cost item the registry has never heard of — a search API, a vector DB, GPU seconds, a render. The item is priced entirely by its `dimensions` (its token rates are 0). `provider` and `item` must match, verbatim, the `vendor` and `item` your SDK sends on `hyperline.cost({ vendor, item, quantity, unit })` — they are lowercased and trimmed, nothing else — and each `dimensions[].key` must match the `unit` of the call it prices: `cost()` writes the quantity to `usage_extra[unit]` and pricing matches a dimension by that exact key, so a key that does not match prices nothing. Idempotent by design so a seed script can be re-run: an open custom item already standing for that (provider, item) is returned as it is, rates untouched, with a 200 instead of a fresh 201 — edit a rate by deleting the item and creating it again. A (provider, item) pair the global registry already prices is refused: that model has a price, and a negotiated rate for it goes through the overrides endpoint. operationId: createAgentCostCatalogItem requestBody: description: Create custom cost item payload content: application/json: schema: type: object properties: provider: type: string minLength: 1 description: >- AI model provider, or the vendor of a custom cost item. This is not an integration connection. example: anthropic item: type: string minLength: 1 description: Custom item name matching the usage payload. example: search dimensions: type: array items: type: object properties: key: type: string pattern: ^[a-z0-9_.]{1,64}$ description: >- Dimension or allowance identifier used by usage payloads and meter results. example: cached_input_tokens rate: type: string maxLength: 40 pattern: ^\d+(\.\d+)?$ description: >- Applied rate. Receipt lines may contain a human-readable rate expression. example: '3' per: type: string enum: - 1m - 1k - unit description: |- Quantity basis for the dimension rate. - 1m: Per million units. - 1k: Per thousand units. - unit: Per single unit. example: 1m required: - key - rate - per minItems: 1 maxItems: 10 description: >- Additional billable dimensions; each key matches a usage_extra key and rates use the owning card's units or USD for cost-catalog dimensions. example: - key: cached_input_tokens rate: '0.3' per: 1m required: - provider - item - dimensions responses: '200': description: The custom cost item already existed content: application/json: schema: type: object properties: provider: type: string description: >- AI model provider, or the vendor of a custom cost item. This is not an integration connection. example: anthropic model: type: string description: >- Model identifier, or custom item identifier. Null on wildcard pricing rows. example: claude-sonnet-5 aliases: type: array items: type: string description: Alternative model names recognized by the cost catalog. example: - claude-sonnet-5-latest input_per_m_tokens: type: string pattern: ^-?\d+(\.\d+)?(e[+-]?\d+)?$/i description: >- Provider cost in USD per million input tokens, as an exact decimal string. example: '3' output_per_m_tokens: type: string pattern: ^-?\d+(\.\d+)?(e[+-]?\d+)?$/i description: >- Provider cost in USD per million output tokens, as an exact decimal string. example: '15' cached_input_per_m_tokens: type: string pattern: ^-?\d+(\.\d+)?(e[+-]?\d+)?$/i description: >- Provider cost in USD per million cached input tokens, as an exact decimal string. example: '0.3' cache_write_per_m_tokens: type: string pattern: ^-?\d+(\.\d+)?(e[+-]?\d+)?$/i description: >- Provider cost in USD per million cache write tokens, as an exact decimal string. example: '3.75' dimensions: type: array items: type: object properties: key: type: string description: >- Dimension or allowance identifier used by usage payloads and meter results. example: cached_input_tokens rate: type: string description: >- Applied rate. Receipt lines may contain a human-readable rate expression. example: '3' per: type: string enum: - 1m - 1k - unit description: |- Quantity basis for the dimension rate. - 1m: Per million units. - 1k: Per thousand units. - unit: Per single unit. example: 1m required: - key - rate - per description: >- Additional billable dimensions; each key matches a usage_extra key and rates use the owning card's units or USD for cost-catalog dimensions. example: - key: cached_input_tokens rate: '0.3' per: 1m effective_from: type: string format: date-time description: Time the price takes effect, as a UTC ISO 8601 timestamp. example: '2026-09-01T00:00:00Z' source: type: string enum: - official - override - custom - unlisted description: |- Source of the model or item cost. - official: Official model price registry. - override: Negotiated workspace cost override. - custom: Workspace-defined cost item. - unlisted: Observed usage without catalog pricing. example: official custom_item_id: type: - string - 'null' description: >- Custom cost-item identifier used to delete the item; null for registry models. example: null override: type: - object - 'null' properties: id: type: string description: Unique Hyperline identifier for this resource. example: d18603dd-7285-4bf5-a45e-88d7de8f37c9 input_per_m_tokens: type: string pattern: ^-?\d+(\.\d+)?(e[+-]?\d+)?$/i description: >- Provider cost in USD per million input tokens, as an exact decimal string. example: '3' output_per_m_tokens: type: string pattern: ^-?\d+(\.\d+)?(e[+-]?\d+)?$/i description: >- Provider cost in USD per million output tokens, as an exact decimal string. example: '15' cached_input_per_m_tokens: type: - string - 'null' pattern: ^-?\d+(\.\d+)?(e[+-]?\d+)?$/i description: >- Provider cost in USD per million cached input tokens, as an exact decimal string. example: '0.3' cache_write_per_m_tokens: type: - string - 'null' pattern: ^-?\d+(\.\d+)?(e[+-]?\d+)?$/i description: >- Provider cost in USD per million cache write tokens, as an exact decimal string. example: '3.75' dimensions: type: array items: type: object properties: key: type: string description: >- Dimension or allowance identifier used by usage payloads and meter results. example: cached_input_tokens rate: type: string description: >- Applied rate. Receipt lines may contain a human-readable rate expression. example: '3' per: type: string enum: - 1m - 1k - unit description: |- Quantity basis for the dimension rate. - 1m: Per million units. - 1k: Per thousand units. - unit: Per single unit. example: 1m required: - key - rate - per description: >- Additional billable dimensions; each key matches a usage_extra key and rates use the owning card's units or USD for cost-catalog dimensions. example: - key: cached_input_tokens rate: '0.3' per: 1m effective_from: type: string format: date-time description: >- Time the price takes effect, as a UTC ISO 8601 timestamp. example: '2026-09-01T00:00:00Z' required: - id - input_per_m_tokens - output_per_m_tokens - cached_input_per_m_tokens - cache_write_per_m_tokens - effective_from description: >- Negotiated workspace cost override, or null when using registry rates. example: null required: - provider - model - aliases - input_per_m_tokens - output_per_m_tokens - cached_input_per_m_tokens - cache_write_per_m_tokens - dimensions - effective_from - source - custom_item_id - override '201': description: '' content: application/json: schema: type: object properties: provider: type: string description: >- AI model provider, or the vendor of a custom cost item. This is not an integration connection. example: anthropic model: type: string description: >- Model identifier, or custom item identifier. Null on wildcard pricing rows. example: claude-sonnet-5 aliases: type: array items: type: string description: Alternative model names recognized by the cost catalog. example: - claude-sonnet-5-latest input_per_m_tokens: type: string pattern: ^-?\d+(\.\d+)?(e[+-]?\d+)?$/i description: >- Provider cost in USD per million input tokens, as an exact decimal string. example: '3' output_per_m_tokens: type: string pattern: ^-?\d+(\.\d+)?(e[+-]?\d+)?$/i description: >- Provider cost in USD per million output tokens, as an exact decimal string. example: '15' cached_input_per_m_tokens: type: string pattern: ^-?\d+(\.\d+)?(e[+-]?\d+)?$/i description: >- Provider cost in USD per million cached input tokens, as an exact decimal string. example: '0.3' cache_write_per_m_tokens: type: string pattern: ^-?\d+(\.\d+)?(e[+-]?\d+)?$/i description: >- Provider cost in USD per million cache write tokens, as an exact decimal string. example: '3.75' dimensions: type: array items: type: object properties: key: type: string description: >- Dimension or allowance identifier used by usage payloads and meter results. example: cached_input_tokens rate: type: string description: >- Applied rate. Receipt lines may contain a human-readable rate expression. example: '3' per: type: string enum: - 1m - 1k - unit description: |- Quantity basis for the dimension rate. - 1m: Per million units. - 1k: Per thousand units. - unit: Per single unit. example: 1m required: - key - rate - per description: >- Additional billable dimensions; each key matches a usage_extra key and rates use the owning card's units or USD for cost-catalog dimensions. example: - key: cached_input_tokens rate: '0.3' per: 1m effective_from: type: string format: date-time description: Time the price takes effect, as a UTC ISO 8601 timestamp. example: '2026-09-01T00:00:00Z' source: type: string enum: - official - override - custom - unlisted description: |- Source of the model or item cost. - official: Official model price registry. - override: Negotiated workspace cost override. - custom: Workspace-defined cost item. - unlisted: Observed usage without catalog pricing. example: official custom_item_id: type: - string - 'null' description: >- Custom cost-item identifier used to delete the item; null for registry models. example: null override: type: - object - 'null' properties: id: type: string description: Unique Hyperline identifier for this resource. example: d18603dd-7285-4bf5-a45e-88d7de8f37c9 input_per_m_tokens: type: string pattern: ^-?\d+(\.\d+)?(e[+-]?\d+)?$/i description: >- Provider cost in USD per million input tokens, as an exact decimal string. example: '3' output_per_m_tokens: type: string pattern: ^-?\d+(\.\d+)?(e[+-]?\d+)?$/i description: >- Provider cost in USD per million output tokens, as an exact decimal string. example: '15' cached_input_per_m_tokens: type: - string - 'null' pattern: ^-?\d+(\.\d+)?(e[+-]?\d+)?$/i description: >- Provider cost in USD per million cached input tokens, as an exact decimal string. example: '0.3' cache_write_per_m_tokens: type: - string - 'null' pattern: ^-?\d+(\.\d+)?(e[+-]?\d+)?$/i description: >- Provider cost in USD per million cache write tokens, as an exact decimal string. example: '3.75' dimensions: type: array items: type: object properties: key: type: string description: >- Dimension or allowance identifier used by usage payloads and meter results. example: cached_input_tokens rate: type: string description: >- Applied rate. Receipt lines may contain a human-readable rate expression. example: '3' per: type: string enum: - 1m - 1k - unit description: |- Quantity basis for the dimension rate. - 1m: Per million units. - 1k: Per thousand units. - unit: Per single unit. example: 1m required: - key - rate - per description: >- Additional billable dimensions; each key matches a usage_extra key and rates use the owning card's units or USD for cost-catalog dimensions. example: - key: cached_input_tokens rate: '0.3' per: 1m effective_from: type: string format: date-time description: >- Time the price takes effect, as a UTC ISO 8601 timestamp. example: '2026-09-01T00:00:00Z' required: - id - input_per_m_tokens - output_per_m_tokens - cached_input_per_m_tokens - cache_write_per_m_tokens - effective_from description: >- Negotiated workspace cost override, or null when using registry rates. example: null required: - provider - model - aliases - input_per_m_tokens - output_per_m_tokens - cached_input_per_m_tokens - cache_write_per_m_tokens - dimensions - effective_from - source - custom_item_id - override '400': description: Invalid request. content: application/json: schema: type: object properties: message: type: string required: - message '409': description: The request conflicts with the current configuration. content: application/json: schema: type: object properties: message: type: string required: - message security: - bearer: [] components: securitySchemes: bearer: type: http scheme: bearer bearerFormat: JWT ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.