Skip to main content
POST
Create workspace

Authorizations

Authorization
string
header
required

Bearer an mk_live_ API key. A key is ORG-SCOPED: it grants full access to every resource in that organization, with no per-endpoint scoping (see the uid pseudo-permission on each operation). Manage keys at https://app.mymarky.ai.

Headers

Idempotency-Key
string | null

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.

Marky-Version
enum<string>

Opt into a dated API version. Omit to stay on the floor (2026-04-08) forever — unpinned clients never break. Pin to a newer date (e.g. 2026-11-03) to receive the newest response shapes. Unknown values fall back to the floor. See https://docs.mymarky.ai for the versioning model.

Available options:
2026-04-08,
2026-07-17,
2026-08-02,
2026-08-04,
2026-08-06,
2026-10-30,
2026-10-31,
2026-11-03
Example:

"2026-11-03"

Body

application/json
name
string
required

Workspace name

design_style
string | null

The brand's whole visual direction as markdown: the place for its colours (exact hex codes, which one leads), fonts, how type is set, logo placement and when the logo appears, imagery and whitespace. Prose at the top is binding on every image; a ## Treatments table underneath lists named looks, one picked per post. SCOPE: it is added to the prompt for AI-GENERATED images. It does NOT reach a template design, so it will not change a batch generated from templates. SIZE: 5000 characters, and writing this field REPLACES the whole value. Plan to the cap before composing; the response's field_budgets entry tells you how much room is left.

brand_style_grid_url
string | null

URL of a rendered 2x2 grid of four sample posts, all in ONE of the treatments from the design_style table — the first look the user kept when they ran /brand-setup. Written by /brand-setup at the end of that run; the app shows it so someone can SEE their look instead of reading it.

strategy
string | null

Social strategy doc as MARKDOWN — the goal we're working toward, who the posts are for, the brand voice, what we're trying right now, what we won't do, cadence and mix, plus a running log of experiments and what we learned. This is the layer an agency revisits each quarter. Write plain markdown (## headings, - bullets, | tables |); the app renders it in a rich-text editor, so no HTML tags — they show up as literal text and spend the size budget without adding meaning. Content pillars, caption rules and calls to action go here too. How graphics look goes in design_style. SIZE: 6000 characters, and writing this field REPLACES the whole doc. A longer value is still saved, but it comes back with a warning you have to act on in the same turn — so plan the doc to the cap BEFORE you compose it, rather than writing long and compacting after. The response's field_budgets entry for this field tells you exactly how much room is left.

description
string | null

Workspace description

industry
string | null

Industry (e.g. 'Real Estate', 'Marketing Agency')

website
string | null

Business website URL

language
string
default:English

Content language, as an ISO 639-1 code (e.g. 'en') or English name (e.g. 'English'). Both accepted.

Response

Successful Response

id
string
required

Workspace ID

created_at
string
required

When the workspace was created

warnings
FieldWarning · object[]
required
read-only

Non-blocking notes about fields that need attention, empty when there is nothing to do. Act on them in the same turn you see them — that is while you still have the content in context.

field_budgets
FieldBudget · object[]
required
read-only

Size ceilings for the fields that get pasted into the prompt for every generated post. READ THIS BEFORE COMPOSING a value for one of these fields — remaining is the room you have, and a budgeted field is REPLACED whole on write, so limit is the real target. Over-budget writes are accepted, not rejected, but they cost a full rewrite to fix.

design_style
string | null

The brand's whole visual direction as markdown: the place for its colours (exact hex codes, which one leads), fonts, how type is set, logo placement and when the logo appears, imagery and whitespace. Prose at the top is binding on every image; a ## Treatments table underneath lists named looks, one picked per post. SCOPE: it is added to the prompt for AI-GENERATED images. It does NOT reach a template design, so it will not change a batch generated from templates. SIZE: 5000 characters, and writing this field REPLACES the whole value. Plan to the cap before composing; the response's field_budgets entry tells you how much room is left.

brand_style_grid_url
string | null

URL of a rendered 2x2 grid of four sample posts, all in ONE of the treatments from the design_style table — the first look the user kept when they ran /brand-setup. Written by /brand-setup at the end of that run; the app shows it so someone can SEE their look instead of reading it.

strategy
string | null

Social strategy doc as MARKDOWN — the goal we're working toward, who the posts are for, the brand voice, what we're trying right now, what we won't do, cadence and mix, plus a running log of experiments and what we learned. This is the layer an agency revisits each quarter. Write plain markdown (## headings, - bullets, | tables |); the app renders it in a rich-text editor, so no HTML tags — they show up as literal text and spend the size budget without adding meaning. Content pillars, caption rules and calls to action go here too. How graphics look goes in design_style. SIZE: 6000 characters, and writing this field REPLACES the whole doc. A longer value is still saved, but it comes back with a warning you have to act on in the same turn — so plan the doc to the cap BEFORE you compose it, rather than writing long and compacting after. The response's field_budgets entry for this field tells you exactly how much room is left.

name
string | null

Workspace name

description
string | null

Workspace description

industry
string | null

Industry category

website
string | null

Business website URL

language
string
default:en

Content language as an ISO 639-1 code (e.g. 'en', 'fr', 'es').

platform_writing_instructions
Platform Writing Instructions · object | null

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_workspace only, not the list endpoint.

events
BusinessEvent · object[]

The workspace's own dated moments: launches, openings, sales, events (e.g. {'name': 'Hope Shop opening', 'date': '2026-10-10', 'kind': 'opening'}). They show up in list_upcoming_moments, and a caption that names one is dated to it. At most 20.

timezone
string | null

The workspace's IANA timezone (e.g. 'Europe/Warsaw'). Posting-schedule slots and *_local times use it, and holidays in moments come from its country. Null when unset: times are then UTC and holidays default to the US. Set with update_workspace.

updated_at
string | null

Last update time

revision_id
string | null

Id of the undo record this write created. Pass it to revert_revisions to put the record back exactly as it was before this call. Set only on the response to a write; null when you read the record.