List timeslots

GET

/v1/accounts/{accountId}/timeslots

const url = 'https://api-v1.tailwind.ai/v1/accounts/example/timeslots';
const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

curl --request GET \
  --url https://api-v1.tailwind.ai/v1/accounts/example/timeslots \
  --header 'Authorization: Bearer <token>'

List all smart schedule timeslots for an account. These are RECURRING WEEKLY rules (day of week + time of day + timezone), not dated occurrences, and they carry no occupancy information. For which specific upcoming times are actually free, use GET /v1/accounts/{accountId}/schedule.

Authorizations

bearerAuth

Parameters

Path Parameters

accountId

required

string

Numeric Tailwind account ID returned by GET /v1/accounts

Responses

200

List of timeslots

application/json

object

data

object

timeslots

Array<object>

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

object

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": {
    "timeslots": [
      {
        "type": "auto-created"
      }
    ]
  }
}

401

Authentication required or invalid bearer credentials

application/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

Resource not found

application/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

string

meta

object

requestId

Unique request ID for debugging

string

Example

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

429

Rate limit exceeded

application/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

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"
  }
}