> ## Documentation Index > Fetch the complete documentation index at: https://docs.mymarky.ai/llms.txt > Use this file to discover all available pages before exploring further. # Create business > Create a new business in your organization. Send an `Idempotency-Key` header to make a retry safe (a resend with the same key returns the original business instead of creating a duplicate). Errors: 401 authentication_required: API key or token is missing, invalid, or revoked. 403 permission_denied: Your plan does not include API access. 403 WORKSPACE_LIMIT_EXCEEDED: You hit your plan's workspace limit. Carries an `upgrade_url` (one-click "add a workspace" screen) and `workspace_limit`. 422 IDEMPOTENCY_KEY_CONFLICT: The Idempotency-Key was reused with a different body. 429 rate_limit_exceeded: You sent too many requests this minute. ## OpenAPI ````yaml public-openapi.json post /api/businesses openapi: 3.1.0 info: title: Marky Public API version: '2026-04-08' description: Create and schedule posts, manage businesses, library, media, and webhooks. servers: - url: https://api.mymarky.ai description: Production security: [] paths: /api/businesses: post: tags: - public-api summary: Create business description: >- Create a new business in your organization. Send an `Idempotency-Key` header to make a retry safe (a resend with the same key returns the original business instead of creating a duplicate). Errors: 401 authentication_required: API key or token is missing, invalid, or revoked. 403 permission_denied: Your plan does not include API access. 403 WORKSPACE_LIMIT_EXCEEDED: You hit your plan's workspace limit. Carries an `upgrade_url` (one-click "add a workspace" screen) and `workspace_limit`. 422 IDEMPOTENCY_KEY_CONFLICT: The Idempotency-Key was reused with a different body. 429 rate_limit_exceeded: You sent too many requests this minute. operationId: create_business parameters: - name: Idempotency-Key in: header required: false schema: anyOf: - type: string - type: 'null' description: >- Optional. Send a unique value (e.g. a UUID) to make this create request safe to retry. A repeat with the same key returns the original response instead of creating a duplicate. Cached for 24h, scoped to your org. Reusing a key with a different body returns 422. title: Idempotency-Key description: >- Optional. Send a unique value (e.g. a UUID) to make this create request safe to retry. A repeat with the same key returns the original response instead of creating a duplicate. Cached for 24h, scoped to your org. Reusing a key with a different body returns 422. requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/BusinessCreateRequest' responses: '201': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/BusinessResponse' '400': description: Error (Stripe-style envelope — match on error.code, not the message) content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' '401': description: Error (Stripe-style envelope — match on error.code, not the message) content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' '403': description: Error (Stripe-style envelope — match on error.code, not the message) content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' '404': description: Error (Stripe-style envelope — match on error.code, not the message) content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' '409': description: Error (Stripe-style envelope — match on error.code, not the message) content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' '429': description: Error (Stripe-style envelope — match on error.code, not the message) content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' '500': description: Error (Stripe-style envelope — match on error.code, not the message) content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' security: - HTTPBearer: [] components: schemas: BusinessCreateRequest: properties: tone: anyOf: - type: string - type: 'null' title: Tone description: >- Brand voice — the tone and personality Marky writes captions in (the 'Profile' field in the app). audience_combined: anyOf: - type: string - type: 'null' title: Audience Combined description: >- The target audience the brand writes for — who the posts are meant to reach (the 'Target Audience' field in the app). caption_writing_rules: anyOf: - type: string - type: 'null' title: Caption Writing Rules description: >- Extra rules Marky follows when writing captions (e.g. 'never use emojis', 'always end with a question'). caption_suffix: anyOf: - type: string - type: 'null' title: Caption Suffix description: >- Text appended to the end of every generated caption (e.g. a hashtag block or a link). custom_caption_prompt: anyOf: - type: string - type: 'null' title: Custom Caption Prompt description: >- A custom instruction injected into caption generation for this business. imagery_preferences: anyOf: - type: string - type: 'null' title: Imagery Preferences description: Guidance on the imagery the brand prefers (style, subjects, mood). tagline: anyOf: - type: string - type: 'null' title: Tagline description: Brand tagline shown on designs. ctas: anyOf: - items: type: string type: array - type: 'null' title: Ctas description: >- Call-to-action phrases Marky can use on designs (e.g. 'Call today', 'Book now'). palettes: anyOf: - items: $ref: '#/components/schemas/Palette' type: array - type: 'null' title: Palettes description: Brand color palettes used on generated designs. header_font: anyOf: - $ref: '#/components/schemas/FontSetting' - type: 'null' description: Font used for headlines on designs. body_font: anyOf: - $ref: '#/components/schemas/FontSetting' - type: 'null' description: Font used for body text on designs. logo_url: anyOf: - type: string - type: 'null' title: Logo Url description: URL of the brand logo. logo_background_color: anyOf: - type: string - type: 'null' title: Logo Background Color description: >- Background color behind the logo on designs (hex, or '#00000000' for transparent). logo_width: anyOf: - type: integer - type: 'null' title: Logo Width description: Logo width in pixels, used when laying the logo onto designs. name: type: string title: Name description: Business name description: anyOf: - type: string - type: 'null' title: Description description: Business description industry: anyOf: - type: string - type: 'null' title: Industry description: Industry (e.g. 'Real Estate', 'Marketing Agency') website: anyOf: - type: string - type: 'null' title: Website description: Business website URL language: type: string title: Language description: >- Content language as its English name (e.g. 'English', 'French', 'Spanish'). default: English additionalProperties: false type: object required: - name title: BusinessCreateRequest BusinessResponse: properties: tone: anyOf: - type: string - type: 'null' title: Tone description: >- Brand voice — the tone and personality Marky writes captions in (the 'Profile' field in the app). audience_combined: anyOf: - type: string - type: 'null' title: Audience Combined description: >- The target audience the brand writes for — who the posts are meant to reach (the 'Target Audience' field in the app). caption_writing_rules: anyOf: - type: string - type: 'null' title: Caption Writing Rules description: >- Extra rules Marky follows when writing captions (e.g. 'never use emojis', 'always end with a question'). caption_suffix: anyOf: - type: string - type: 'null' title: Caption Suffix description: >- Text appended to the end of every generated caption (e.g. a hashtag block or a link). custom_caption_prompt: anyOf: - type: string - type: 'null' title: Custom Caption Prompt description: >- A custom instruction injected into caption generation for this business. imagery_preferences: anyOf: - type: string - type: 'null' title: Imagery Preferences description: Guidance on the imagery the brand prefers (style, subjects, mood). tagline: anyOf: - type: string - type: 'null' title: Tagline description: Brand tagline shown on designs. ctas: anyOf: - items: type: string type: array - type: 'null' title: Ctas description: >- Call-to-action phrases Marky can use on designs (e.g. 'Call today', 'Book now'). palettes: anyOf: - items: $ref: '#/components/schemas/Palette' type: array - type: 'null' title: Palettes description: Brand color palettes used on generated designs. header_font: anyOf: - $ref: '#/components/schemas/FontSetting' - type: 'null' description: Font used for headlines on designs. body_font: anyOf: - $ref: '#/components/schemas/FontSetting' - type: 'null' description: Font used for body text on designs. logo_url: anyOf: - type: string - type: 'null' title: Logo Url description: URL of the brand logo. logo_background_color: anyOf: - type: string - type: 'null' title: Logo Background Color description: >- Background color behind the logo on designs (hex, or '#00000000' for transparent). logo_width: anyOf: - type: integer - type: 'null' title: Logo Width description: Logo width in pixels, used when laying the logo onto designs. id: type: string title: Id description: Business ID name: anyOf: - type: string - type: 'null' title: Name description: Business name description: anyOf: - type: string - type: 'null' title: Description description: Business description industry: anyOf: - type: string - type: 'null' title: Industry description: Industry category website: anyOf: - type: string - type: 'null' title: Website description: Business website URL language: type: string title: Language description: Content language default: English platform_writing_instructions: anyOf: - additionalProperties: type: string type: object - type: 'null' title: Platform Writing Instructions description: >- The user's customized per-platform caption-writing instructions (empty when none set). Keys are canonical platform names (e.g. 'instagram', 'linkedIn') plus 'common' (applies to all platforms). Follow the matching entry when writing a caption or platform_overrides caption — the user's instructions ALWAYS outrank generic platform best practices. Update via PATCH (merge semantics). Returned by get_business only, not the list endpoint. created_at: type: string format: date-time title: Created At description: When the business was created updated_at: anyOf: - type: string format: date-time - type: 'null' title: Updated At description: Last update time type: object required: - id - created_at title: BusinessResponse ErrorEnvelope: description: >- The body of every non-2xx response. `detail` is retained on internal routes for backward-compatibility while the frontend migrates to reading `error.code`. properties: error: $ref: '#/components/schemas/ErrorDetail' required: - error title: ErrorEnvelope type: object HTTPValidationError: properties: detail: items: $ref: '#/components/schemas/ValidationError' type: array title: Detail type: object title: HTTPValidationError Palette: properties: name: type: string title: Name description: Label for this palette default: My Palette colors: items: type: string type: array title: Colors description: >- Hex color codes in the palette, e.g. ['#0d0c0c', '#FFFFFF', '#121212']. text_color: anyOf: - type: string - type: 'null' title: Text Color description: Hex color used for body text on designs accent_color: anyOf: - type: string - type: 'null' title: Accent Color description: Hex accent/brand color background_color: anyOf: - type: string - type: 'null' title: Background Color description: Hex background color for designs additionalProperties: false type: object title: Palette FontSetting: properties: name: type: string title: Name description: >- Font family name, e.g. 'Montserrat'. Must be a font Marky can load (a Google Font, or one with a direct url below). url: anyOf: - type: string - type: 'null' title: Url description: >- Direct font file URL. Leave null for a Google Font (Marky resolves it by name). additionalProperties: false type: object required: - name title: FontSetting ErrorDetail: properties: type: type: string title: Type description: >- Broad error category derived from the HTTP status (invalid_request_error, authentication_error, permission_error, not_found_error, rate_limit_error, api_error). code: $ref: '#/components/schemas/ErrorCode' description: >- Stable, machine-readable error code. Match on THIS, never on the message. Codes never change even when the message is reworded. message: type: string title: Message description: Human-readable explanation. For display/logging only — do not parse. doc_url: type: string title: Doc Url description: Link to the docs entry for this error code. param: anyOf: - type: string - type: 'null' title: Param description: The offending request field, when the error is field-specific. request_id: anyOf: - type: string - type: 'null' title: Request Id description: >- The id of this request (also returned as the X-Request-Id header). Quote it to support so they can find the exact request in our logs. type: object required: - type - code - message - doc_url title: ErrorDetail ValidationError: properties: loc: items: anyOf: - type: string - type: integer type: array title: Location msg: type: string title: Message type: type: string title: Error Type type: object required: - loc - msg - type title: ValidationError ErrorCode: type: string enum: - authentication_required - permission_denied - resource_not_found - rate_limit_exceeded - validation_error - internal_error - already_exists - invalid_request - WORKSPACE_NOT_SUPPORTED - INSUFFICIENT_CREDITS - BUSINESS_CREDIT_LIMIT_EXCEEDED - NO_ENABLED_TOPICS - GENERATION_CAP_REACHED - CHECKOUT_BLOCKED - INVALID_API_KEY - SOCIAL_TOKEN_EXPIRED - PAYMENT_REQUIRED - NO_CONNECTED_SOCIALS - NOT_ENOUGH_POSTS_FOR_TOPICS - WORKSPACE_LIMIT_EXCEEDED - PHONE_NOT_VERIFIED - FILE_TOO_LARGE - SUBSCRIPTION_ALREADY_ACTIVE - UPSTREAM_PROVIDER_ERROR - PLATFORM_MEDIA_UNSUPPORTED - SOCIAL_CONNECT_FAILED - NO_PHOTO_SOURCE - TEMPLATE_FORMAT_MISMATCH - INVALID_CSV_ROW - IMAGE_GENERATION_FAILED - POST_RENDER_FAILED - POST_DESIGN_SELECTION_FAILED - POST_CONTENT_GENERATION_FAILED - POST_IDEATION_FAILED - IDEMPOTENCY_KEY_CONFLICT title: ErrorCode description: >- The full set of stable `error.code` values the API can return. Two groups: (1) GENERIC codes the global handler derives from the HTTP status or message keyword for plain raises (see api_errors._error_code + the handlers), and (2) the typed BUSINESS codes (mirror of ErrorType) for raises the frontend must tell apart from other same-status errors. This enum exists so OpenAPI emits an `enum` for error.code — a canonical list in the docs and a typed union for codegen — instead of a bare string. It does NOT validate runtime responses (those are plain dicts built in _build_error_response), so a code missing here only means incomplete docs, never a 500. The test_error_code_enum_covers_* tests keep it in sync with ErrorType + _error_code so it can't silently drift. securitySchemes: HTTPBearer: type: http scheme: bearer ````