> ## Documentation Index > Fetch the complete documentation index at: https://docs.mystacks.ai/llms.txt > Use this file to discover all available pages before exploring further. # Create a stack > Create and immediately publish a stack. Creates a stack owned by the manager identified by your API key. The stack is published immediately. There is no separate draft or publish step. Try it sends a real request to staging. Creation immediately publishes a stack. Enter a new Idempotency-Key for each intended new stack. ## Idempotency `Idempotency-Key` must contain non-whitespace text. Keys are scoped to your manager account and stack creation. Accepted keys do not expire automatically. A retry with the same key and equivalent original input returns the same stack ID. It returns that stack's **current** configuration and ETag. If the stack has been updated, this can differ from the first creation response. The retry does not revert changes or create a revision. The following differences do not change creation input identity: * JSON whitespace and object-field order. * Allocation-entry order. * Token-address capitalization that still passes address validation. The exact name, token identities, integer weights, and schedule preset must match. Changing any of them under the same key returns `409 conflict`. Use [update a stack](/api-reference/stacks/update) to change an existing stack. When matching requests arrive together, the first successfully saved creation establishes the result. There is no fixed application limit on key length. A key that exceeds supported storage size returns `400 invalid_request` without creating a stack. A UUID is a practical creation key. ## Errors | Status | Code | Cause | | ------ | ----------------- | ---------------------------------------------------------------------------------------------- | | `400` | `invalid_request` | Missing or blank creation key, unsupported key size, malformed JSON, or invalid configuration. | | `409` | `conflict` | The creation key was already used with different input. | [Shared errors](/api-reference/errors) cover authentication, body size, and service failures. After an uncertain creation result, retry with the same key and original input. ## OpenAPI ````yaml POST /manager/stacks openapi: 3.1.0 info: title: MyStacks Manager API version: 1.0.0 description: >- Create, read, and update your stacks. MyStacks generates API keys and supplies them to wealth managers. Authenticate with the supplied key in the Authorization header using the Bearer scheme. Your key identifies your manager account. Every response includes X-Request-Id. The API saves configuration. Automated scheduled trading is still being built. servers: - url: https://api-staging.mystacks.ai description: MyStacks staging backend security: - ManagerApiKey: [] tags: - name: Stacks description: Manage your stack configurations and current revisions. paths: /manager/stacks: parameters: - $ref: '#/components/parameters/RequestId' post: tags: - Stacks summary: Create a stack description: >- Create and immediately publish a complete stack. The first transaction committed for this manager and Idempotency-Key establishes the creation receipt. Identical retries return 200 with the same stack ID and its current complete configuration and ETag. They do not change configuration or create a revision. Different input under the same key returns 409. Input identity preserves the exact name, integer weights, and schedule preset. Token addresses are normalized to lowercase and allocations sorted by address. JSON formatting, object-field order, allocation order, and valid address capitalization do not change input identity. Saving configuration does not execute trades. operationId: createStack parameters: - $ref: '#/components/parameters/IdempotencyKey' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateStackRequest' example: name: Example stack allocation: - token_address: '0x117cc2133c37b721f49de2a7a74833232b3b4c0c' weight_bps: 6000 - token_address: '0xd0601ce157db5bdc3162bbac2a2c8af5320d9eec' weight_bps: 4000 schedule: preset: daily responses: '200': description: >- Identical creation retry. Returns the original stack ID with its current complete configuration and revision. headers: X-Request-Id: $ref: '#/components/headers/RequestId' ETag: $ref: '#/components/headers/ETag' content: application/json: schema: $ref: '#/components/schemas/ManagerStack' example: id: bf4bc5e9-0d9e-454c-bc1c-30abc120b074 current_revision_id: e137435f-83ce-4b3c-86ae-75d6462487b6 name: Example stack allocation: - token_address: '0x117cc2133c37b721f49de2a7a74833232b3b4c0c' weight_bps: 6000 - token_address: '0xd0601ce157db5bdc3162bbac2a2c8af5320d9eec' weight_bps: 4000 schedule: preset: daily '201': description: Stack created and immediately published. headers: X-Request-Id: $ref: '#/components/headers/RequestId' ETag: $ref: '#/components/headers/ETag' content: application/json: schema: $ref: '#/components/schemas/ManagerStack' example: id: bf4bc5e9-0d9e-454c-bc1c-30abc120b074 current_revision_id: e137435f-83ce-4b3c-86ae-75d6462487b6 name: Example stack allocation: - token_address: '0x117cc2133c37b721f49de2a7a74833232b3b4c0c' weight_bps: 6000 - token_address: '0xd0601ce157db5bdc3162bbac2a2c8af5320d9eec' weight_bps: 4000 schedule: preset: daily '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '409': $ref: '#/components/responses/Conflict' '413': $ref: '#/components/responses/PayloadTooLarge' '429': $ref: '#/components/responses/RateLimited' '500': $ref: '#/components/responses/InternalError' '503': $ref: '#/components/responses/ServiceUnavailable' components: parameters: RequestId: name: X-Request-Id in: header required: false description: >- Optional request trace ID. A nonempty value is echoed in the response. Missing or empty values cause a UUID to be generated. schema: type: string IdempotencyKey: name: Idempotency-Key in: header required: true description: >- Required for creation. Must contain non-whitespace text. Reuse the exact same manager-scoped key and original input after an uncertain result. Keys do not expire automatically. No fixed application length cap applies. A key beyond the database receipt index storage limit returns 400 and rolls back the complete creation. schema: type: string minLength: 1 pattern: \S example: example-stack-create-001 schemas: CreateStackRequest: type: object additionalProperties: false properties: name: $ref: '#/components/schemas/StackName' allocation: $ref: '#/components/schemas/Allocation' schedule: $ref: '#/components/schemas/Schedule' required: - name - allocation - schedule description: >- Complete stack configuration. Unknown fields are rejected in the body and nested objects. The request body must not exceed 262144 bytes. example: name: Example stack allocation: - token_address: '0x117cc2133c37b721f49de2a7a74833232b3b4c0c' weight_bps: 6000 - token_address: '0xd0601ce157db5bdc3162bbac2a2c8af5320d9eec' weight_bps: 4000 schedule: preset: daily ManagerStack: type: object additionalProperties: false properties: id: type: string format: uuid description: Stable stack identifier. example: bf4bc5e9-0d9e-454c-bc1c-30abc120b074 current_revision_id: type: string format: uuid description: Identifier of this complete saved configuration revision. example: e137435f-83ce-4b3c-86ae-75d6462487b6 name: $ref: '#/components/schemas/StackName' allocation: $ref: '#/components/schemas/NormalizedAllocation' schedule: $ref: '#/components/schemas/Schedule' required: - id - current_revision_id - name - allocation - schedule description: >- Current complete configuration. No subscriber, balance, performance, or execution data is included. example: id: bf4bc5e9-0d9e-454c-bc1c-30abc120b074 current_revision_id: e137435f-83ce-4b3c-86ae-75d6462487b6 name: Example stack allocation: - token_address: '0x117cc2133c37b721f49de2a7a74833232b3b4c0c' weight_bps: 6000 - token_address: '0xd0601ce157db5bdc3162bbac2a2c8af5320d9eec' weight_bps: 4000 schedule: preset: daily StackName: type: string minLength: 1 pattern: ^(?![\s\S]*\u0000)[\s\S]*\S[\s\S]*$ description: >- Must contain non-whitespace text and must not contain U+0000. Accepted names retain their exact whitespace. No separate name-length limit applies within the body size limit. example: Example stack Allocation: type: array minItems: 1 maxItems: 30 items: $ref: '#/components/schemas/AllocationItem' description: >- The complete target allocation. Weights must total exactly 10000. Duplicate token identities are rejected after lowercase normalization. When supplied in PATCH, this list replaces the full saved allocation. Omitted tokens are removed. example: - token_address: '0x117cc2133c37b721f49de2a7a74833232b3b4c0c' weight_bps: 6000 - token_address: '0xd0601ce157db5bdc3162bbac2a2c8af5320d9eec' weight_bps: 4000 Schedule: type: object additionalProperties: false properties: preset: type: string enum: - hourly - daily - weekly - monthly description: >- Saved UTC schedule preset. Planned boundaries are minute zero each hour, 00:00 each day, 00:00 each Monday, or 00:00 on the first day of each month. Custom schedules and timezone fields are invalid. Automated scheduled trading is still being built. example: daily required: - preset description: Schedule configuration only. Saving a preset does not execute trades. example: preset: daily NormalizedAllocation: type: array minItems: 1 maxItems: 30 items: $ref: '#/components/schemas/NormalizedAllocationItem' description: >- Complete saved allocation. Addresses are lowercase, unique, and ordered by token address. Weights total exactly 10000. example: - token_address: '0x117cc2133c37b721f49de2a7a74833232b3b4c0c' weight_bps: 6000 - token_address: '0xd0601ce157db5bdc3162bbac2a2c8af5320d9eec' weight_bps: 4000 Error: type: object additionalProperties: false properties: code: type: string enum: - invalid_request - unauthorized - not_found - conflict - payload_too_large - rate_limited - internal_error - service_unavailable description: Machine-readable error category. example: invalid_request message: type: string description: >- Public-safe explanation. No field-by-field validation details are returned. example: invalid request body request_id: type: string description: >- Matches the response X-Request-Id header. This can be a caller-supplied string, not only a UUID. example: d28e1ad4-2ca8-4f35-b590-8bf3b53abc81 required: - code - message - request_id example: code: invalid_request message: invalid request body request_id: d28e1ad4-2ca8-4f35-b590-8bf3b53abc81 AllocationItem: type: object additionalProperties: false properties: token_address: $ref: '#/components/schemas/TokenAddress' weight_bps: $ref: '#/components/schemas/WeightBps' required: - token_address - weight_bps example: token_address: '0x117cc2133c37b721f49de2a7a74833232b3b4c0c' weight_bps: 6000 NormalizedAllocationItem: type: object additionalProperties: false properties: token_address: $ref: '#/components/schemas/NormalizedTokenAddress' weight_bps: $ref: '#/components/schemas/WeightBps' required: - token_address - weight_bps example: token_address: '0x117cc2133c37b721f49de2a7a74833232b3b4c0c' weight_bps: 6000 TokenAddress: type: string pattern: ^0x[0-9a-fA-F]{40}$ description: >- A token from the 30-asset Robinhood Chain mainnet whitelist (chain ID 4663). Use a lowercase or correctly checksummed address. The pattern checks address syntax only. The server also enforces checksum validity and whitelist membership before normalizing identity to lowercase. USDG is not an allocation token. See [supported assets](/api-reference/assets) for all accepted addresses. example: '0x117cc2133c37b721f49de2a7a74833232b3b4c0c' WeightBps: type: integer minimum: 0 maximum: 10000 description: >- Target weight in basis points. 10000 means 100%. Zero is allowed. All allocation weights together must total exactly 10000. example: 6000 NormalizedTokenAddress: type: string pattern: ^0x[0-9a-f]{40}$ enum: - '0xd0601ce157db5bdc3162bbac2a2c8af5320d9eec' - '0x117cc2133c37b721f49de2a7a74833232b3b4c0c' - '0x4a0e65a3eccec6dbe60ae065f2e7bb85fae35eea' - '0xccee82fe024c36fa15e1005ede3e9e4787e23d09' - '0x05b37fb53a299a1b874a619e1c4c404d52c36f4c' - '0xff080c8ce2e5feadaca0da81314ae59d232d4afd' - '0xa30fa36db767ad9ed3f7a60fc79526fb4d56d344' - '0xec262a75e413fafd0df80480274532c79d42da09' - '0xd5f3879160bc7c32ebb4dc785f8a4f505888de68' - '0x1b0e319c6a659f002271b69db8a7df2f911c153e' - '0x12f190a9f9d7d37a250758b26824b97ce941bf54' - '0xaf3d76f1834a1d425780943c99ea8a608f8a93f9' - '0x58ffe4a942d3885baa22d7520691f611ef09e7aa' - '0x86923f96303d656e4aa86d9d42d1e57ad2023fdc' - '0x2e0847e8910a9732eb3fb1bb4b70a580adad4fe3' - '0x4ea005168d7f09a7a0ba9d1def21a479950e44c2' - '0xe93237c50d904957cf27e7b1133b510c669c2e74' - '0x322f0929c4625ed5bad873c95208d54e1c003b2d' - '0xc0d6457c16cc70d6790dd43521c899c87ce02f35' - '0x9e7abd3c9139d14e4c86dce0e455aab7a0c2fb3e' - '0xb90a19ff0af67f7779aff50a882a9cff42446400' - '0xc72b96e0e48ecd4dc75e1e45396e26300bc39681' - '0x894e1ec2d74ffe5aef8dc8a9e84686accb964f2a' - '0x1d11f0496982706c5e14a514d4e79f2e6bde4516' - '0x411efb0e7f985935daec3d4c3ebaea0d0ad7d89f' - '0x5e81213613b6b86eab4c6c50d718d34359459786' - '0xc9a981fee1f9dec688bb123ccdecc63d0debfc4e' - '0x6330d8c3178a418788df01a47479c0ce7ccf450b' - '0xdf0992e440dd0be65bd8439b609d6d4366bf1cb5' - '0x48e39e56acdba37b09020c0b734a613c9a2f100a' description: >- A supported trading token address normalized to lowercase. See [supported assets](/api-reference/assets) for names and symbols. example: '0x117cc2133c37b721f49de2a7a74833232b3b4c0c' headers: RequestId: description: >- Request trace ID. A nonempty incoming X-Request-Id is reused. If missing or empty, the server generates a UUID. Error request_id values match this header. schema: type: string example: d28e1ad4-2ca8-4f35-b590-8bf3b53abc81 ETag: description: >- Current revision ID enclosed in double quotes. PATCH does not require If-Match and does not enforce conditional updates. schema: type: string pattern: ^"[0-9a-fA-F-]{36}"$ example: '"e137435f-83ce-4b3c-86ae-75d6462487b6"' responses: BadRequest: description: Invalid JSON, configuration, pagination, stack UUID, or creation key. headers: X-Request-Id: $ref: '#/components/headers/RequestId' content: application/json: schema: $ref: '#/components/schemas/Error' example: code: invalid_request message: invalid request body request_id: d28e1ad4-2ca8-4f35-b590-8bf3b53abc81 Unauthorized: description: >- Missing or invalid manager credential, or verified identity lacks required identity fields or a canonical lowercase UUID external ID. headers: X-Request-Id: $ref: '#/components/headers/RequestId' content: application/json: schema: $ref: '#/components/schemas/Error' example: code: unauthorized message: invalid manager credential request_id: d28e1ad4-2ca8-4f35-b590-8bf3b53abc81 Conflict: description: >- The manager already used this creation key with different normalized input. headers: X-Request-Id: $ref: '#/components/headers/RequestId' content: application/json: schema: $ref: '#/components/schemas/Error' example: code: conflict message: Idempotency-Key was already used with different input request_id: d28e1ad4-2ca8-4f35-b590-8bf3b53abc81 PayloadTooLarge: description: Request body exceeds 262144 bytes. headers: X-Request-Id: $ref: '#/components/headers/RequestId' content: application/json: schema: $ref: '#/components/schemas/Error' example: code: payload_too_large message: request body exceeds 262144 bytes request_id: d28e1ad4-2ca8-4f35-b590-8bf3b53abc81 RateLimited: description: >- API-key verification was rate limited. No fixed quota or Retry-After header contract is published. headers: X-Request-Id: $ref: '#/components/headers/RequestId' content: application/json: schema: $ref: '#/components/schemas/Error' example: code: rate_limited message: manager verification rate limited request_id: d28e1ad4-2ca8-4f35-b590-8bf3b53abc81 InternalError: description: >- Unexpected internal failure or conflicting saved manager identity binding. headers: X-Request-Id: $ref: '#/components/headers/RequestId' content: application/json: schema: $ref: '#/components/schemas/Error' example: code: internal_error message: an unexpected error occurred request_id: d28e1ad4-2ca8-4f35-b590-8bf3b53abc81 ServiceUnavailable: description: >- API-key verification timed out or is unavailable. No access is granted and no stack changes occur. headers: X-Request-Id: $ref: '#/components/headers/RequestId' content: application/json: schema: $ref: '#/components/schemas/Error' example: code: service_unavailable message: manager verification is unavailable request_id: d28e1ad4-2ca8-4f35-b590-8bf3b53abc81 securitySchemes: ManagerApiKey: type: http scheme: bearer description: >- Enter the API key supplied by MyStacks. The playground adds the `Authorization: Bearer` prefix for you. ````