Treasure Data Postback API

openapi: 3.2.0
info:
  title: api-v2 Postback API
  description: This spec is for Postback API v2 (records.in.treasuredata.com)
  version: 2.0.0
servers:
- url: https://{region}.records.in.treasuredata.com
  variables:
    region:
      default: us01
      description: TD region host prefix (e.g. us01, eu01, ap02)
security:
- TD1Authorization: []
- XTDWriteKey: []
tags:
- name: Postback
paths:
  /postback/v3/event/{database_name}/{table_name}:
    parameters:
    - in: path
      name: database_name
      schema:
        type: string
      required: true
      description: Name of the database the table is in. Name may contain letters, numbers or _ .
    - in: path
      name: table_name
      schema:
        type: string
      required: true
      description: Name of the table to log data to. Name may contain letters, numbers or _ .
    post:
      summary: POST Postback API v2
      operationId: postPostbackAPIv2
      description: 'Send data in POST payload to the v2 Postback endpoint.


        Authentication is **header-only**. Provide one of:

        1. `Authorization: TD1 `

        2. `X-TD-Write-Key: `


        URL-path keys (`?td_write_key=...`) accepted by the legacy endpoint are **not** supported here. If both headers are sent, `Authorization` takes precedence.


        Note: Requests with an invalid API key return a 200 HTTP status code. This behavior is intentional and ensures a fast response, preventing ingestion from being canceled due to slow response. After the response is returned, the endpoint performs asynchronous validations. If the API key is invalid, an authentication failure will be raised despite the initial 200 status.


        Maximum request body size is 1,048,064 bytes; larger payloads are rejected with `413`.'
      requestBody:
        description: 'The body of the request can be any key value pairs you want to send. Specify JSON as a body. The JSON content immediately becomes a record in Treasure Data. Also include `Content-Type: application/json` in HTTP request headers.


          Suggested Parameters:


          **td_record_time**: UNIX timestamp value, to set time column in Treasure Data. If it''s not specified, the time records were received is used instead. Received timestamps that are older than 7 days, and newer than 3 days ahead of the current date are ignored.\

          **td_global_id**: TD global ID \

          **td_ua**: user-agent


          Parameter values are processed as the data type string, and cannot be changed at the ingestion time.

          '
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: true
            examples:
              generic:
                summary: Generic Example
                value:
                  param1: value1
                  param2: value2
              td:
                summary: TD Example
                value:
                  td_global_id: xxxxx
                  td_ua: user agent
      responses:
        '200':
          $ref: '#/components/responses/200'
        '400':
          $ref: '#/components/responses/400'
        '403':
          $ref: '#/components/responses/403'
        '413':
          $ref: '#/components/responses/413'
      tags:
      - Postback
components:
  responses:
    '413':
      description: Payload Too Large (request body exceeds 1,048,064 bytes)
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/AllResponse'
    '403':
      description: Forbidden
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/AllResponse'
    '400':
      description: Bad Request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/AllResponse'
    '200':
      description: Success.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/AllResponse'
  schemas:
    AllResponse:
      type: object
      title: Response
      description: response for all objects
      properties:
        Content-Type:
          type: string
          example: application/json
        Date:
          type: string
          format: date-time
          example: Wed, DD MM YYYY xx:yy:zz GMT
        Strict-Transport-Security:
          type: string
          example: max-age=31536000
        Content-Length:
          type: integer
          example: 2
        Connection:
          type: string
          example: keep-alive
  securitySchemes:
    XTDWriteKey:
      type: apiKey
      in: header
      name: X-TD-Write-Key
    TD1Authorization:
      type: apiKey
      in: header
      name: Authorization
      description: 'Format: `TD1 <APIKEY>`'