Skip to content
Tailwind API

Create timeslot

POST
/v1/accounts/{accountId}/timeslots
curl --request POST \
  --url https://api-v1.tailwind.ai/v1/accounts/example/timeslots \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "dayPreference": 1, "time": "example", "timezone": "example" }'

Add one recurring weekly slot to the account’s smart schedule: a day of week, a 24-hour HH:MM time, and optionally the IANA timezone the time is expressed in. Without timezone the account’s own timezone is used, and the request is rejected with a 400 if the account has none set. The slot is created with type manual, the same type the dashboard gives a user-placed slot. Free: managing the schedule costs no credits, in the dashboard or here.

There is no duplicate check, matching the dashboard: two identical calls create two slots at the same time, so read GET /v1/accounts/{accountId}/timeslots first when adding to an existing schedule. Evergreen (SmartLoop) slots cannot be created here.

Authorizations

Section titled “Authorizations”

Parameters

Section titled “Parameters”

Path Parameters

Section titled “Path Parameters”
accountId
required
string

Numeric Tailwind account ID returned by GET /v1/accounts

Request Bodyrequired

Section titled “Request Bodyrequired”
Media typeapplication/json
object
dayPreference
required

Day of week (0 = Sunday through 6 = Saturday)

integer
<= 6
time
required

Time of day as 24-hour HH:MM (e.g. “09:30”), in timezone

string
/^(?:[01][0-9]|2[0-3]):[0-5][0-9]$/
timezone

IANA timezone the time is expressed in (e.g. America/New_York). Defaults to the account’s own timezone; required if the account has none set.

string
Examplegenerated
{
  "dayPreference": 1,
  "time": "example",
  "timezone": "example"
}

Responses

Section titled “Responses”

201

Section titled “201”

Timeslot created

Media typeapplication/json
object
data
object
timeslot

A recurring weekly posting rule, not a dated occurrence. Carries no occupancy — see ScheduleEntry.

object
id

Timeslot ID

string
accountId

Account ID

string
dayPreference

Day of week (0-6, where 0 is Sunday)

integer
<= 6
timePreference

Time of day as a zero-padded 24-hour HHMM string (e.g. “0930”), in timezone

string
timezone

Timezone (e.g., America/New_York)

string
type

How the slot was added: generated by a rebuild, picked from Tailwind’s suggestions, or placed by hand (including every slot created or edited through this API)

string
Allowed values: auto-created recommended manual
scheduleId

Schedule ID, when associated with a schedule

integer
pinUuid

Pin UUID, when associated with a pin

integer
sendAt

Unix timestamp of one occurrence, predicted when the slot was written. Not maintained afterwards; use GET /v1/accounts/{accountId}/schedule for real upcoming times.

integer
meta
object
requestId

Unique request ID for debugging

string
Example
{
  "data": {
    "timeslot": {
      "type": "auto-created"
    }
  }
}

400

Section titled “400”

Invalid request

Media typeapplication/json
object
error
object
code

Error code

string
message

Error message

string
reason

Machine-readable denial reason. Present on PAYMENT_REQUIRED errors: insufficient_credits, trial_exhausted, no_access, account_not_connected, legacy_post_limit_exceeded.

string
resolve_url

Present on PAYMENT_REQUIRED errors: where the denial can be resolved. Reason-specific, because buying credits does not clear a trial, access or connection denial. Requests sent with X-Request-Source: mcp receive an informational plans page instead, so agent surfaces never present a purchase link.

string
meta
object
requestId

Unique request ID for debugging

string
Example
{
  "error": {
    "code": "BAD_REQUEST",
    "message": "Invalid request body"
  },
  "meta": {
    "requestId": "abc123"
  }
}

401

Section titled “401”

Authentication required or invalid bearer credentials

Media typeapplication/json
object
error
object
code

Error code

string
message

Error message

string
reason

Machine-readable denial reason. Present on PAYMENT_REQUIRED errors: insufficient_credits, trial_exhausted, no_access, account_not_connected, legacy_post_limit_exceeded.

string
resolve_url

Present on PAYMENT_REQUIRED errors: where the denial can be resolved. Reason-specific, because buying credits does not clear a trial, access or connection denial. Requests sent with X-Request-Source: mcp receive an informational plans page instead, so agent surfaces never present a purchase link.

string
meta
object
requestId

Unique request ID for debugging

string
Example
{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid API key"
  },
  "meta": {
    "requestId": "abc123"
  }
}

404

Section titled “404”

Resource not found

Media typeapplication/json
object
error
object
code

Error code

string
message

Error message

string
reason

Machine-readable denial reason. Present on PAYMENT_REQUIRED errors: insufficient_credits, trial_exhausted, no_access, account_not_connected, legacy_post_limit_exceeded.

string
resolve_url

Present on PAYMENT_REQUIRED errors: where the denial can be resolved. Reason-specific, because buying credits does not clear a trial, access or connection denial. Requests sent with X-Request-Source: mcp receive an informational plans page instead, so agent surfaces never present a purchase link.

string
meta
object
requestId

Unique request ID for debugging

string
Example
{
  "error": {
    "code": "NOT_FOUND",
    "message": "Account not found"
  },
  "meta": {
    "requestId": "abc123"
  }
}

409

Section titled “409”

Another write to this account’s smart schedule holds the lock — in practice a rebuild, which replaces every slot and so cannot run alongside other changes. Nothing was written; retry in a moment.

Media typeapplication/json
object
error
object
code

Error code

string
message

Error message

string
reason

Machine-readable denial reason. Present on PAYMENT_REQUIRED errors: insufficient_credits, trial_exhausted, no_access, account_not_connected, legacy_post_limit_exceeded.

string
resolve_url

Present on PAYMENT_REQUIRED errors: where the denial can be resolved. Reason-specific, because buying credits does not clear a trial, access or connection denial. Requests sent with X-Request-Source: mcp receive an informational plans page instead, so agent surfaces never present a purchase link.

string
meta
object
requestId

Unique request ID for debugging

string
Example
{
  "error": {
    "code": "CONFLICT",
    "message": "This account's schedule is being updated elsewhere. Retry in a moment."
  },
  "meta": {
    "requestId": "abc123"
  }
}

429

Section titled “429”

Rate limit exceeded

Media typeapplication/json
object
error
object
code

Error code

string
message

Error message

string
reason

Machine-readable denial reason. Present on PAYMENT_REQUIRED errors: insufficient_credits, trial_exhausted, no_access, account_not_connected, legacy_post_limit_exceeded.

string
resolve_url

Present on PAYMENT_REQUIRED errors: where the denial can be resolved. Reason-specific, because buying credits does not clear a trial, access or connection denial. Requests sent with X-Request-Source: mcp receive an informational plans page instead, so agent surfaces never present a purchase link.

string
meta
object
requestId

Unique request ID for debugging

string
Example
{
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Daily rate limit of 5000 requests exceeded. Resets at midnight UTC."
  },
  "meta": {
    "requestId": "abc123"
  }
}