> ## Documentation Index > Fetch the complete documentation index at: https://docs.bily.ai/llms.txt > Use this file to discover all available pages before exploring further. # Generate Static Creative with Saved Request > Pending release; not a deployed-availability claim. Save one actor-owned request before planning and return its ID promptly. Read source-filtered unresolved requests and current admission first. For a genuinely fresh submission, durably retain the current advertised prefix plus a new UUIDv4 before one explicitly approved POST. Never automatically repeat or replace an unknown key. Acceptance is not image completion; read the same request and linked ready generation. This creates a Bily draft only, never a platform ad. ## OpenAPI ````yaml /openapi.json post /creative-intelligence/{storeUrl}/generation-requests openapi: 3.1.0 info: title: Bily API version: 1.0.0 description: >- Discover stores, read analytics and commerce data, inspect connections, and run explicitly authorized actions with the Bily API. contact: name: Bily support email: support@bily.ai servers: - url: https://app.bily.ai/api/customer/v1 description: Production security: - ApiKeyAuth: [] - BearerAuth: [] tags: - name: Identity description: Discover the identity and organizations attached to a key. - name: Stores description: Discover stores within an organization. - name: Store data description: Read store profiles, readiness, catalogs, and connected accounts. - name: Commerce description: Run scoped commerce reads and explicitly approved GraphQL mutations. - name: Analytics description: >- Read normalized advertising, attribution, product, customer, and cohort metrics. - name: Analytics SQL description: Run constrained read-only SQL over store-scoped Bily datasets. - name: Customer journeys description: Read customer touchpoints within an authenticated store scope. - name: Connections description: Inspect available connections, support, and advertising assets. - name: Supported actions description: Synchronize connections and update supported advertising assets. - name: Campaign actions description: Create or clone supported advertising campaign resources. - name: Ad drafts and jobs description: Save, review, publish and reconcile immutable advertising changes. - name: Creative library description: >- Analyze references and retain generated images separately from ad publication. - name: Tracking connections description: >- List and manage store-scoped tracking connections without returning credential secrets. - name: Tracking evidence description: >- Inspect installation, incoming receipts, reviewed events and destination evidence within one workspace. paths: /creative-intelligence/{storeUrl}/generation-requests: post: tags: - Creative library summary: Generate Static Creative with Saved Request description: >- Pending release; not a deployed-availability claim. Save one actor-owned request before planning and return its ID promptly. Read source-filtered unresolved requests and current admission first. For a genuinely fresh submission, durably retain the current advertised prefix plus a new UUIDv4 before one explicitly approved POST. Never automatically repeat or replace an unknown key. Acceptance is not image completion; read the same request and linked ready generation. This creates a Bily draft only, never a platform ad. operationId: ads-request-static-creative parameters: - name: storeUrl in: path required: true description: Exact workspace URL returned by GET /context. schema: type: string - $ref: '#/components/parameters/OrganizationId' - name: x-bily-generation-request-attempt in: header required: false description: >- Fresh UUIDv4 for this one POST only when consuming qualified non-admission proof; never an authorization token or key rewrite. schema: type: string pattern: >- ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$ requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/AdsRequestStaticCreativeInput' responses: '200': description: >- Read the returned identifier until processing reaches a terminal state. Acceptance alone does not confirm completion. headers: x-request-id: schema: type: string description: Keep this identifier for diagnostics. Cache-Control: schema: type: string const: private, no-store description: Do not place these responses in shared caches. content: application/json: schema: type: object required: - request - storeUrl properties: request: $ref: '#/components/schemas/CreativeGenerationRequest' storeUrl: type: string example: storeUrl: store.example.com request: protocol: creative-generation-request-v1 id: request-example status: failed phase: failed generationId: null sourceIntelligenceId: analysis-example quality: draft aspectRatio: '1:1' saveToLibrary: false pinnedAt: null createdAt: 1800000000 updatedAt: 1800000000 expiresAt: 1800172800 lastError: protocol: creative-generation-error-v1 code: strategy_failed phase: planning message: Generation planning failed. '202': description: >- Read the returned identifier until processing reaches a terminal state. Acceptance alone does not confirm completion. headers: x-request-id: schema: type: string description: Keep this identifier for diagnostics. Cache-Control: schema: type: string const: private, no-store description: Do not place these responses in shared caches. content: application/json: schema: type: object required: - request - storeUrl properties: request: $ref: '#/components/schemas/CreativeGenerationRequest' storeUrl: type: string example: storeUrl: store.example.com request: protocol: creative-generation-request-v1 id: request-example status: queued phase: awaiting_dispatch generationId: null sourceIntelligenceId: analysis-example quality: draft aspectRatio: '1:1' saveToLibrary: false pinnedAt: null createdAt: 1800000000 updatedAt: 1800000000 expiresAt: 1800172800 lastError: null '400': description: >- Generic errors remain unknown. Only the exact same-submission verified receipt can prove non-admission; a later explicit request must reread availability. Never automatically retry or replace the key. headers: Cache-Control: schema: type: string const: private, no-store x-bily-workspace-resource-type: schema: enum: - website - shopify-store description: >- Required for a qualified receipt and equal to its canonical resourceType. content: application/json: schema: anyOf: - allOf: - $ref: '#/components/schemas/Error' - not: required: - nonAdmission - allOf: - $ref: >- #/components/schemas/CreativeGenerationQualifiedRejection - properties: code: const: invalid_request nonAdmission: properties: code: const: invalid_request - allOf: - $ref: >- #/components/schemas/CreativeGenerationQualifiedRejection - properties: code: const: source_unavailable nonAdmission: properties: code: const: source_unavailable '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '409': description: >- Generic errors remain unknown. Only the exact same-submission verified receipt can prove non-admission; a later explicit request must reread availability. Never automatically retry or replace the key. headers: Cache-Control: schema: type: string const: private, no-store x-bily-workspace-resource-type: schema: enum: - website - shopify-store description: >- Required for a qualified receipt and equal to its canonical resourceType. content: application/json: schema: anyOf: - allOf: - $ref: '#/components/schemas/Error' - not: required: - nonAdmission - allOf: - $ref: >- #/components/schemas/CreativeGenerationQualifiedRejection - properties: code: const: admission_changed nonAdmission: properties: code: const: admission_changed '410': description: >- The saved request expired. This does not authorize automatic resubmission. content: application/json: schema: $ref: '#/components/schemas/Error' '429': description: >- Generic errors remain unknown. Only the exact same-submission verified receipt can prove non-admission; a later explicit request must reread availability. Never automatically retry or replace the key. headers: Cache-Control: schema: type: string const: private, no-store x-bily-workspace-resource-type: schema: enum: - website - shopify-store description: >- Required for a qualified receipt and equal to its canonical resourceType. content: application/json: schema: anyOf: - allOf: - $ref: '#/components/schemas/Error' - not: required: - nonAdmission - allOf: - $ref: >- #/components/schemas/CreativeGenerationQualifiedRejection - properties: code: const: generation_limit nonAdmission: properties: code: const: generation_limit '500': $ref: '#/components/responses/ServerError' '502': $ref: '#/components/responses/BadGateway' '503': $ref: '#/components/responses/ServiceUnavailable' components: parameters: OrganizationId: name: x-bily-organization-id in: header required: false description: >- An organization ID returned by GET /context or GET /organizations. Omit it when a scoped key supplies the organization. Otherwise provide it when no organization is selected. schema: type: string example: org_01J8W7T9G3E6ZQ4M2K5N8P1R0S schemas: AdsRequestStaticCreativeInput: type: object additionalProperties: false required: - sourceIntelligenceId - idempotencyKey properties: sourceIntelligenceId: type: string pattern: ^[A-Za-z0-9._~-]{1,256}$ idempotencyKey: type: string pattern: ^[A-Za-z0-9._~-]{1,256}$ quality: enum: - draft - polished type: string aspectRatio: enum: - '1:1' - '4:5' - '9:16' - '2:3' type: string instruction: type: string maxLength: 500 saveToLibrary: type: boolean CreativeGenerationRequest: type: object additionalProperties: false required: - protocol - id - status - phase - generationId - sourceIntelligenceId - quality - aspectRatio - createdAt - updatedAt - expiresAt - lastError - saveToLibrary - pinnedAt properties: protocol: const: creative-generation-request-v1 type: string id: type: string pattern: ^[A-Za-z0-9._~-]{1,256}$ status: enum: - queued - processing - ready - failed - reconcile_required type: string phase: enum: - awaiting_dispatch - preparing - planning - rendering - saving - completed - failed - reconcile_required type: string generationId: anyOf: - type: 'null' - type: string pattern: ^[A-Za-z0-9._~-]{1,256}$ sourceIntelligenceId: type: string pattern: ^[A-Za-z0-9._~-]{1,256}$ quality: enum: - draft - polished type: string aspectRatio: enum: - '1:1' - '4:5' - '9:16' - '2:3' type: string saveToLibrary: type: boolean pinnedAt: anyOf: - type: integer - type: 'null' createdAt: type: integer updatedAt: type: integer expiresAt: type: integer lastError: anyOf: - type: 'null' - type: object additionalProperties: false required: - protocol - code - phase - message properties: protocol: const: creative-generation-error-v1 type: string code: enum: - dispatch_uncertain - preparation_failed - strategy_uncertain - strategy_failed - render_uncertain - render_failed - save_uncertain - interrupted - request_expired type: string phase: enum: - dispatch - preparing - planning - rendering - saving type: string message: type: string Error: type: object required: - error properties: error: type: string example: Store not found requestId: type: string description: Present on some server errors. details: description: Optional safe details for an action failure. retryAfter: type: - string - 'null' additionalProperties: true CreativeGenerationQualifiedRejection: type: object properties: resourceUrl: type: string resourceType: type: string enum: - website - shopify-store storeUrl: type: string error: type: string maxLength: 500 code: enum: - invalid_request - source_unavailable - admission_changed - generation_limit type: string nonAdmission: $ref: '#/components/schemas/CreativeGenerationNonAdmission' required: - resourceUrl - resourceType - storeUrl - error - code - nonAdmission additionalProperties: false description: >- Shape alone is not rejection authority. Verify the original one-send POST nonce, exact key SHA256/source, canonical workspace and private,no-store JSON response. Unknown or mismatched evidence keeps the original owner and GET-only recovery. CreativeGenerationNonAdmission: type: object additionalProperties: false required: - protocol - outcome - scope - attemptId - requestKeySha256 - sourceIntelligenceId - code properties: protocol: const: creative-generation-non-admission-v1 type: string outcome: const: not_admitted type: string scope: const: this_submission type: string attemptId: type: string pattern: >- ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$ requestKeySha256: type: string pattern: ^[a-f0-9]{64}$ sourceIntelligenceId: type: string pattern: ^[A-Za-z0-9._~-]{1,256}$ minLength: 1 maxLength: 256 code: enum: - invalid_request - source_unavailable - admission_changed - generation_limit type: string responses: Unauthorized: description: Authentication is missing or invalid. headers: x-request-id: description: The request identifier selected or generated by Bily. schema: type: string content: application/json: schema: $ref: '#/components/schemas/Error' Forbidden: description: The identity or API key is not allowed to perform this request. headers: x-request-id: description: The request identifier selected or generated by Bily. schema: type: string content: application/json: schema: $ref: '#/components/schemas/Error' NotFound: description: The resource was not found in the caller's accessible scope. headers: x-request-id: description: The request identifier selected or generated by Bily. schema: type: string content: application/json: schema: $ref: '#/components/schemas/Error' ServerError: description: Bily could not complete the request. headers: x-request-id: description: The request identifier selected or generated by Bily. schema: type: string content: application/json: schema: $ref: '#/components/schemas/Error' BadGateway: description: A dependent Bily operation was temporarily unavailable. headers: x-request-id: description: The request identifier selected or generated by Bily. schema: type: string content: application/json: schema: $ref: '#/components/schemas/Error' ServiceUnavailable: description: >- Authentication or a required data source is temporarily unavailable. Honor Retry-After when present; do not interpret this as an invalid key or an empty dataset. headers: x-request-id: description: The request identifier selected or generated by Bily. schema: type: string content: application/json: schema: $ref: '#/components/schemas/Error' securitySchemes: ApiKeyAuth: type: apiKey in: header name: x-api-key description: >- A server-side Bily API key created under Settings > AI tools > Access keys. Select the intended workspace before creating it. BearerAuth: type: http scheme: bearer bearerFormat: Bily API key description: An alternative way to send the same server-side Bily API key. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.