messages

One message, full representation

GET/v1/messages/{id}

Always the full representation. Accepts no query parameters (not even view): any parameter returns 400 bad_request.

Authentication: CF-Access-Client-Id + CF-Access-Client-Secret. Operation id getMessage.

Parameters

Name	In	Type	Description
`id` required	path	Id	Message id (32 lowercase hex characters). example `9b1e4c7a2d5f8e0b3a6c9d2e5f8a1b4c`

Request example

Shell

curl -s https://api.mint.xcorp.cc/v1/messages/9b1e4c7a2d5f8e0b3a6c9d2e5f8a1b4c \
  -H "CF-Access-Client-Id: $MINT_ID" \
  -H "CF-Access-Client-Secret: $MINT_SECRET"

Responses

200The full message.

Headers

`x-records-new`	integer	Distinct messages in this response charged now (first delivery this month). Sent on every response once your client is identified; 0 on routes that do not charge.
`x-budget-remaining`	integer	Distinct messages left in this month's budget, after this response. Sent on every response once your client is identified.
`x-request-id`	string	Request id. Quote it when contacting support.

Body application/json

Schema: FullMessage

Field	Type	Description
`id`	Id
`institution`	string	Institution slug (see `/v1/institutions`).
`date`	Date
`seq`	integer	Order of the message within its date and institution. It replaces the send time, which this API does not provide. minimum `0`
`title`	string
`channel`	Channel
`tags`	array of string	Tag names.
`summary`	string \| null	Summary written by XCORP.
`transactional`	boolean
`tone`	string \| null
`urgency`	string \| null
`product`	null \| object	Main product, from `/v1/products`.
`product.id`	integer
`product.name`	string
`product_text`	string \| null	Product as written in the catalog entry.
`extra_products`	array of string	Names of other products in the message.
`cta`	string \| null	Call to action.
`valid_until`	null \| Date	Offer validity date, if stated.
`personalized`	boolean \| null
`format`	string \| null
`partner`	string \| null
`rate`	string \| null	Rate as written in the creative.
`rate_cdi`	number \| null	Rate as a percentage of CDI, when applicable.
`language`	string \| null
`images`	integer	Number of images; fetch with `/v1/messages/{id}/images/{n}`. minimum `0`
`content`	Content

Example: A full message

JSON

{
  "id": "9b1e4c7a2d5f8e0b3a6c9d2e5f8a1b4c",
  "institution": "nubank",
  "date": "2026-11-08",
  "seq": 3,
  "title": "Ganhe cashback no Pix no crédito",
  "channel": "push",
  "tags": [
    "Cashback",
    "Pix"
  ],
  "summary": "Offers 2% cashback on Pix paid with the credit card until month end.",
  "transactional": false,
  "tone": "promocional",
  "urgency": "media",
  "product": {
    "id": 42,
    "name": "Cartão de crédito"
  },
  "product_text": "Cartão de crédito",
  "extra_products": [
    "Pix"
  ],
  "cta": "Aproveite",
  "valid_until": "2026-11-30",
  "personalized": false,
  "format": "texto",
  "partner": null,
  "rate": null,
  "rate_cdi": null,
  "language": "pt",
  "images": 1,
  "content": {
    "source": "third_party_untrusted",
    "text": "Pix no crédito com 2% de cashback. Válido até 30/11."
  }
}

400Invalid, unknown or repeated parameter (bad_request, with detail = {param, why}), date before the window (window, first accepted date in detail.first_date) or invalid cursor (bad_cursor: tampered, expired, from another credential, other filters or another day; restart without cursor). BadRequest

Body application/json

Schema: Error

Field	Type	Description
`error`	string	one of `"bad_request"`, `"window"`, `"bad_cursor"`, `"forbidden"`, `"disabled"`, `"access_ended"`, `"not_found"`, `"method_not_allowed"`, `"rate_limited"`, `"internal"`
`message`	string	What happened and what to do, in English.
`detail` optional	any	Extra information: `{"param", "why"}` for every `bad_request`, `{"first_date"}` for `window`, `{"limit"}` for `rate_limited`.

Example

JSON

{
  "error": "window",
  "message": "Dates before 2026-10-09 are outside the 30-day window. Use since/from on or after that date; for older trends use /v1/stats.",
  "detail": {
    "first_date": "2026-10-09"
  }
}

403No valid credential (forbidden), access disabled (disabled) or access period over (access_ended). Do not retry; contact XCORP. Forbidden

Body application/json

Schema: Error

Field	Type	Description
`error`	string	one of `"bad_request"`, `"window"`, `"bad_cursor"`, `"forbidden"`, `"disabled"`, `"access_ended"`, `"not_found"`, `"method_not_allowed"`, `"rate_limited"`, `"internal"`
`message`	string	What happened and what to do, in English.
`detail` optional	any	Extra information: `{"param", "why"}` for every `bad_request`, `{"first_date"}` for `window`, `{"limit"}` for `rate_limited`.

Example

JSON

{
  "error": "access_ended",
  "message": "Your access period has ended. Contact XCORP."
}

404Message does not exist, is outside the window or is not visible to you; or an unknown institution, tag or product in a filter. All these cases look the same. NotFound

Body application/json

Schema: Error

Field	Type	Description
`error`	string	one of `"bad_request"`, `"window"`, `"bad_cursor"`, `"forbidden"`, `"disabled"`, `"access_ended"`, `"not_found"`, `"method_not_allowed"`, `"rate_limited"`, `"internal"`
`message`	string	What happened and what to do, in English.
`detail` optional	any	Extra information: `{"param", "why"}` for every `bad_request`, `{"first_date"}` for `window`, `{"limit"}` for `rate_limited`.

Example

JSON

{
  "error": "not_found",
  "message": "Not found. Messages exist here only for the last 30 days; check ids and slugs against the catalogs."
}

405Only GET is allowed (HEAD and OPTIONS too return 405). MethodNotAllowed

Headers

allow "GET" Allowed methods: GET.

Body application/json

Schema: Error

Field	Type	Description
`error`	string	one of `"bad_request"`, `"window"`, `"bad_cursor"`, `"forbidden"`, `"disabled"`, `"access_ended"`, `"not_found"`, `"method_not_allowed"`, `"rate_limited"`, `"internal"`
`message`	string	What happened and what to do, in English.
`detail` optional	any	Extra information: `{"param", "why"}` for every `bad_request`, `{"first_date"}` for `window`, `{"limit"}` for `rate_limited`.

Example

JSON

{
  "error": "method_not_allowed",
  "message": "This API is read-only. Use GET."
}

429A limit of your access plan was reached. detail.limit is minute (requests per minute), day (requests per day), images (images per day) or budget (distinct messages per month). Wait retry-after seconds. Your limits: /v1/usage. RateLimited

Headers

`retry-after`	integer	Seconds to wait before retrying.
`x-request-id`	string	Request id. Quote it when contacting support.

Body application/json

Schema: Error

Field	Type	Description
`error`	string	one of `"bad_request"`, `"window"`, `"bad_cursor"`, `"forbidden"`, `"disabled"`, `"access_ended"`, `"not_found"`, `"method_not_allowed"`, `"rate_limited"`, `"internal"`
`message`	string	What happened and what to do, in English.
`detail` optional	any	Extra information: `{"param", "why"}` for every `bad_request`, `{"first_date"}` for `window`, `{"limit"}` for `rate_limited`.

Example

JSON

{
  "error": "rate_limited",
  "message": "Too many requests per minute. Wait for retry-after seconds, then continue.",
  "detail": {
    "limit": "minute"
  }
}

500Unexpected error (internal). Retry later; quote x-request-id to support. Internal

Headers

x-request-id string Request id. Quote it when contacting support.

Body application/json

Schema: Error

Field	Type	Description
`error`	string	one of `"bad_request"`, `"window"`, `"bad_cursor"`, `"forbidden"`, `"disabled"`, `"access_ended"`, `"not_found"`, `"method_not_allowed"`, `"rate_limited"`, `"internal"`
`message`	string	What happened and what to do, in English.
`detail` optional	any	Extra information: `{"param", "why"}` for every `bad_request`, `{"first_date"}` for `window`, `{"limit"}` for `rate_limited`.

Example

JSON

{
  "error": "internal",
  "message": "Unexpected error. Retry later and quote x-request-id if it persists."
}

503Service temporarily disabled for all clients (disabled). Retry after retry-after seconds. Disabled

Headers

`retry-after`	integer	Seconds to wait before retrying.
`x-request-id`	string	Request id. Quote it when contacting support.

Body application/json

Schema: Error

Field	Type	Description
`error`	string	one of `"bad_request"`, `"window"`, `"bad_cursor"`, `"forbidden"`, `"disabled"`, `"access_ended"`, `"not_found"`, `"method_not_allowed"`, `"rate_limited"`, `"internal"`
`message`	string	What happened and what to do, in English.
`detail` optional	any	Extra information: `{"param", "why"}` for every `bad_request`, `{"first_date"}` for `window`, `{"limit"}` for `rate_limited`.

Example

JSON

{
  "error": "disabled",
  "message": "The service is temporarily disabled. Try again later."
}

One message, full representation

#Parameters

#Request example

#Responses

Parameters

Request example

Responses