> ## 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. # Create a new operating-instructions version > Author a new operating-instructions version. The new version number is computed atomically as MAX(version)+1 for the storefront. Does not auto-activate — call the activate endpoint to swap the storefront's active pointer. ## OpenAPI ````yaml /v2/storefront-api-v2.yaml post /operating-instructions 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.interchange.io/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.interchange.io/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: /operating-instructions: post: tags: - Storefront summary: Create a new operating-instructions version description: >- Author a new operating-instructions version. The new version number is computed atomically as MAX(version)+1 for the storefront. Does not auto-activate — call the activate endpoint to swap the storefront's active pointer. operationId: createOperatingInstructions requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateOperatingInstructionsBody' responses: '201': description: Create a new operating-instructions version content: application/json: schema: $ref: '#/components/schemas/OperatingInstructionsResponse' '400': description: Bad request content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '401': description: Unauthorized 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: CreateOperatingInstructionsBody: type: object properties: content: type: string minLength: 1 maxLength: 50000 description: >- Markdown body the merchandising agent will use for product packaging, naming, selection, and explanation. Structured prices/floors/currencies belong in Playbook pricing; brand/operator discounts belong in Buyer Discounts and Buyer Instructions; buyer-visible channels and accepted countries belong in the listing; Product Marketing Media Kits are source material only; advertiser/category/creative eligibility belongs in AI Business Rules. notes: description: >- Operator note describing why this version was created (e.g. "tighten brand-safety rules"). Not surfaced to buyers; visible in the version history UI. type: string maxLength: 2000 activate: default: false description: >- When true, create and activate this immutable version atomically. Defaults to false. type: boolean doctrine: description: >- The selling doctrine this version carries (AI-5870): the qualification strategy the merchandising agent applies BEFORE it composes anything — when to pitch in full, when to counter-pitch with a reframe, and when to pass with a branded decline. Supply exactly one of `variant` or `thresholds`; supplying both is rejected. Omit the whole object to carry no doctrine, which composes under the platform default (every brief the catalogue can serve gets a full pitch). Doctrine is versioned and activated exactly like the prose above, because it IS these instructions grown: reverting is activating the prior version. allOf: - $ref: '#/components/schemas/SellingDoctrineBody' required: - content description: >- Request body for creating a new operating-instructions version and optionally activating it atomically. OperatingInstructionsResponse: type: object properties: id: type: string description: Surrogate id of the version row (BIGINT serialized as string). example: '42' storefrontId: type: string description: Storefront the version belongs to (BIGINT serialized as string). example: '1234' version: type: integer minimum: 1 maximum: 9007199254740991 description: >- Per-storefront version number. Monotone, never reused. The first version a storefront authors is 1. example: 3 content: type: string description: Markdown body consumed by the Merchandising Agent. notes: nullable: true description: Operator note about why this version was authored. type: string isActive: type: boolean description: >- Whether this version is the Storefront's active operating instructions (the version the Merchandising Agent will use on the next composition). createdAt: type: string format: date-time pattern: >- ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$ description: >- Creation timestamp (ISO 8601). Rows are immutable so there is no updatedAt. createdBy: nullable: true description: >- User id of the operator who authored the version (BIGINT serialized as string). Null when authored by a system or service-token caller. type: string ownershipIssues: type: array items: type: object properties: area: type: string enum: - pricing - discounts - markets - acceptance_policy canonicalOwner: type: string enum: - selling_terms - buyer_discounts - business_profile - acceptance_policy canonicalSurface: type: string enum: - playbook_pricing - buyer_discounts - discovery_card - business_rules message: type: string required: - area - canonicalOwner - canonicalSurface - message additionalProperties: false description: >- Canonical-ownership conflicts detected in this immutable version. Empty for versions that keep pricing, discounts, markets, and acceptance facts in their owning storefront surfaces. doctrine: description: >- The selling doctrine this version composes under (AI-5870) — always resolved, never null: a version that stored none reads the platform default with `isDefault: true`. allOf: - $ref: '#/components/schemas/SellingDoctrineResponse' required: - id - storefrontId - version - content - notes - isActive - createdAt - createdBy - ownershipIssues - doctrine additionalProperties: false description: >- A single operating-instructions version for a storefront. Versions are immutable; updates produce a new row. 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 SellingDoctrineBody: anyOf: - $ref: '#/components/schemas/SellingDoctrineAdoptVariant' - $ref: '#/components/schemas/SellingDoctrineSetThresholds' description: >- The selling doctrine to store on this version. Either adopt one of the three named strategies — 'premium_scarcity_house' (qualify hard, pass often, hold price), 'volume_partner' (counter nearly everything, lead with packaging math), or 'consultative' (counter-first, heavy honest counter, invite a re-brief) — or state the thresholds yourself. Supply EXACTLY ONE of `variant` or `thresholds` — a request carrying both, or neither, is rejected rather than resolved by precedence, because either resolution would silently discard half of what the caller asked for. Thresholds that match no named strategy read back as 'custom'. The platform's own balance, 'house_default', is not adoptable by name: it is what applies when no doctrine is set, so clear the doctrine to return to it. SellingDoctrineResponse: type: object properties: variant: type: string enum: - house_default - premium_scarcity_house - volume_partner - consultative - custom thresholds: $ref: '#/components/schemas/SellingDoctrineThresholds' isDefault: type: boolean description: >- True when this version carries no stored doctrine and the platform default is standing in. A storefront is "configured" for doctrine purposes only once this is false on its active version. required: - variant - thresholds - isDefault additionalProperties: false description: >- The doctrine an operating-instructions version carries, always resolved: a version with none reads the platform default with `isDefault: true`, so a reader never has to decide what absence means. 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 SellingDoctrineAdoptVariant: type: object properties: variant: type: string enum: - premium_scarcity_house - volume_partner - consultative required: - variant additionalProperties: false SellingDoctrineSetThresholds: type: object properties: thresholds: $ref: '#/components/schemas/SellingDoctrineThresholds' required: - thresholds additionalProperties: false SellingDoctrineThresholds: type: object properties: minimumCategoryFit: type: number minimum: 0 maximum: 1 description: >- The share of the brief's stated category and channel terms this catalogue must actually serve before the seller pitches in full. 1 means only a brief the catalogue covers completely earns a pitch; 0 means every brief does. counterAppetite: type: number minimum: 0 maximum: 1 description: >- How far below the pitch bar the seller will still answer, with a counter-pitch instead of a pass. 0 never counters — a brief that misses the bar is declined. 1 counters everything the catalogue touches at all. floorPosture: type: string enum: - hold_floor - flex_floor description: >- What to do when the buyer states a budget and no composed line could be priced. 'hold_floor' declines rather than negotiate from nothing; 'flex_floor' counters and invites a re-brief. required: - minimumCategoryFit - counterAppetite - floorPosture additionalProperties: false securitySchemes: bearerAuth: type: http scheme: bearer description: API key or access token ````