Skip to main contentlogoCreated with Sketch.
  • Start for free

    • Introduction

    Last updated: 2018-08-07

    Use the Db2 Warehouse on Cloud API to access data, view and create database objects, administer, and monitor your Db2 Warehouse on Cloud service.
     

    Attention: This is the DEPRECATED Version 1 of the Db2 Warehouse on Cloud REST API documentation. To view the latest version, click here.

    To view other deprecated versions of the REST API documentation, click V2 and V3.

    Root URL

    The context root for the Db2 Warehouse on Cloud API is /dashdb-api/.

    Error handling

    This API uses standard HTTP response codes to indicate whether a method completed successfully. A 200 response indicates success. A 400 type response is some sort of failure.

    Security

    Every request must include the Authorization HTTP header with the value Bearer [access_token]. An access token can be obtained with the /auth/tokens endpoint, and it is used by Db2 Warehouse on Cloud to identify who you are. Db2 Warehouse on Cloud negotiates SSL connections using the TLS v1.2 protocol.

    If you are using the latest version of cURL, protocol negotiation will
happen automatically using TLS v1.2.
If you are using an older version of cURL, you will need to specify the
`--tlsv1.2` option in your cURL commands.

    Methods

    List the contents of the home directory

    List the files and folders contained in the home directory.

    GET /home

    Request

    Request Body

    home_bodyInput

    A timestamp in the format "yyyyMMdd HH:mm:ss z". When specified, the list contains only files and folders created after the specified timestamp.

    Examples:
    View

    Response

    Response Body

    SuccessResponse

    Status Code

    • 200

      Ok

    • 400

      Bad Request

    • 401

      Unauthorized

    • 404

      Not Found

    • 405

      Method Not Allowed

    No Sample Response

    This method does not specify any sample responses.

    Upload a file to the home directory

    Uploads the specified source file to the home directory.

    POST /home

    Request

    Form Parameters

    • data
      Required*
      binary

      Full path to the source data file on Windows, or relative path on UNIX based operating systems. For each additional file: -F '[name]=@"[filename]"', where [name] is a unique name.

    Response

    Response Body

    SuccessResponse

    Status Code

    • 200

      Ok

    • 400

      Bad Request

    • 401

      Unauthorized

    • 404

      Not Found

    • 405

      Method Not Allowed

    No Sample Response

    This method does not specify any sample responses.

    Delete a file or a folder in the home directory

    If a file is specified, then that file is deleted. If a folder is specified, then that folder is deleted; the folder must be empty.

    DELETE /home/{file_or_folder}

    Request

    Path Parameters

    • file_or_folder
      Required*
      string

      The path of a file or folder relative to the home directory.

    Response

    Response Body

    SuccessResponse

    Status Code

    • 200

      Ok

    • 400

      Bad Request

    • 401

      Unauthorized

    • 404

      Not Found

    • 405

      Method Not Allowed

    No Sample Response

    This method does not specify any sample responses.

    Get the contents of a file or list the contents of a folder relative to the home directory

    If a file is specified, then the contents of the file is returned. If a folder is specified, then a list of its files and folders is returned.

    GET /home/{file_or_folder}

    Request

    Custom Headers

    • Accept
      string

      Allowable values: [application/octet-stream,application/json]

    Path Parameters

    • file_or_folder
      Required*
      string

      The path of a file or folder relative to the home directory.

    Request Body

    home_bodyInput

    A timestamp in the format "yyyyMMdd HH:mm:ss z". When specified, the list contains only files and folders created after the specified timestamp.

    Examples:
    View

    Response

    Response Body

    SuccessResponse

    Status Code

    • 200

      Ok

    • 400

      Bad Request

    • 401

      Unauthorized

    • 404

      Not Found

    • 405

      Method Not Allowed

    No Sample Response

    This method does not specify any sample responses.

    Upload a file to a folder relative to the home directory

    Uploads the specified source file to a folder relative to the home directory. Folders in the path are created implicitly.

    POST /home/{folder}

    Request

    Path Parameters

    • folder
      Required*
      string

      The target path of the folder relative to the home directory into which the file should be uploaded.

    Form Parameters

    • data
      Required*
      binary

      Full path to the source data file on Windows, or relative path on UNIX based operating systems. For each additional file: -F '[name]=@"[filename]"', where [name] is a unique name.

    Response

    Response Body

    SuccessResponse

    Status Code

    • 200

      Ok

    • 400

      Bad Request

    • 401

      Unauthorized

    • 404

      Not Found

    • 405

      Method Not Allowed

    No Sample Response

    This method does not specify any sample responses.

    Load local delimited data into a table

    Create a load job that streams delimited data from one or more CSV, XLS, or XLSX files and loads it into the specified table. This POST request is asynchronous and returns before the load job is complete. The parameters specified in the POST request apply to all files included in the same request. If different parameters are needed, load the data using a separate POST request.

    Use the GET /load/{tableName} or GET /load/{loadID} endpoint to retrieve the status of the load job, and the GET /home/{filename} endpoint to retrieve a detailed load log file.

    POST /load/local/del/{tableName}

    Request

    Path Parameters

    • tableName
      Required*
      string

      The schema and table where the data is loaded (schema.'tableName'). The table must exist before the data is loaded.

    Query Parameters

    • hasHeaderRow
      boolean

      Indicates if the source data files include column names in a header row. If this option is selected for a multi-file load job, all files must contain a header row. Default value is "false".

      Default: false

    • delimiter
      string

      Column delimiter used in the source file. Valid values are hexadecimal values 0x01 to 0x7F, excluding line-feed (0x0A), carriage return (0x0D), space (0x20), and decimal point (0x2E). You can enter either the hexadecimal or the character value. Default value is "," (corresponds to 0x2C). If a load job includes one or more XLS or XLSX files, all files must use the default delimiter (,).

      Default: ,

    • loadAction
      string

      Specify if the data is inserted as new data or replaces the existing data in the target table. Valid values are "insert" or "replace". Default value is "insert".

      Allowable values: [insert,replace]

      Default: insert

    • codePage
      int32

      The character encoding of the source file. Valid values are listed in Supported territory codes and code pages. Default value is "1208" (corresponds to UTF-8).

      Default: 1208

    • hasDateTypes
      boolean

      Indicates if the data contains date types. This sets the default date formats for Date (YYYY-MM-DD), Time (HH:MM:SS) and Timestamp (YYYY-MM-DD HH:MM:SS) if they aren't individually set. The default value is "false".

      Default: false

    • dateFormat
      string

      A valid date format, such as "DD-MM-YY", "YYYY-MMM-DD", "DD/MM/YYY", "M/D/YYYY", "M/DD", "YYYY". For a full list of supported formats, see 'Valid file type modifiers for the load utility: ASCII file formats (ASC/DEL)' in the LOAD command reference. Default value is "YYYY-MM-DD".

      Default: YYYY-MM-DD

    • timeFormat
      string

      A valid time format, such as "HH-MM-SS", "H:MM:SS TT", "HH:MM", "H:MM TT", "H:M", "H:M:S". For a full list of supported formats, see 'Valid file type modifiers for the load utility: ASCII file formats (ASC/DEL)' in the LOAD command reference. Default value is "HH:MM:SS".

      Default: HH:MM:SS

    • timestampFormat
      string

      A valid timestamp format, such as "YYYY-MM-DD HH:MM:SS", "DD/MM/YYYY H:MM TT", "MMM DD YYYY HH:MM:SS TT". For a full list of supported formats, see 'Valid file type modifiers for the load utility: ASCII file formats (ASC/DEL)' in the LOAD command reference. Default value is "YYYY-MM-DD HH:MM:SS".

      Default: YYYY-MM-DD HH:MM:SS

    Form Parameters

    • loadFile
      Required*
      binary

      Full path to the source data file on Windows, or relative path on UNIX based operating systems. For each additional file: -F 'loadFile=@"/[filePath]/[fileName.csv]"', where loadFile is unique.

    Response

    Response Body

    LoadPostResponse

    Status Code

    • 200

      Ok

    • 400

      Bad Request

    • 401

      Unauthorized

    • 404

      Not Found

    • 405

      Method Not Allowed

    Example responses
    • {
  "errorMessageCode": "NONE",
  "message": "LOAD started successfully.",
  "result": {
    "END_TIME": "",
    "LOAD_ID": 1234567890,
    "LOAD_LOGFILE": "loadlogs/load_1234567890_DASH123456_ORDER_DETAILS_20160101-094119-CST.json",
    "LOAD_STATUS": "RUNNING",
    "ROWS_COMMITTED": "",
    "ROWS_DELETED": "",
    "ROWS_LOADED": "",
    "ROWS_READ": "",
    "ROWS_REJECTED": "",
    "ROWS_SKIPPED": "",
    "SCHEMA": "DASH123456",
    "START_TIME": "20160101 09:41:19 CST",
    "TABLE": "ORDER_DETAILS"
  },
  "resultCode": "SUCCESS"
}

    Get information on load jobs based on loadID

    Get detailed information about an active or completed load job with the specified loadID. The command will fail if there is no load job with the specified loadID that is associated with the current user.

    GET /load/{loadID}

    Request

    Path Parameters

    • loadID
      Required*
      string

      ID of the load job.

    Response

    Response Body

    LoadGetIdResponse

    Status Code

    • 200

      Ok

    • 400

      Bad Request

    • 401

      Unauthorized

    • 404

      Not Found

    • 405

      Method Not Allowed

    Example responses
    • {
  "errorMessageCode": "NONE",
  "message": "LOAD retrieved successfully",
  "result": {
    "errorMessageCode": "NONE",
    "message": "Load completed successfully.",
    "result": {
      "END_TIME": "20160101 09:41:27 CST",
      "LOAD_ID": 1234567890,
      "LOAD_LOGFILE": "loadlogs/load_1234567890_DASH123456_ORDER_DETAILS_20160101-094119-CST.json",
      "LOAD_STATUS": "COMPLETE",
      "ROWS_COMMITTED": 334518,
      "ROWS_DELETED": 0,
      "ROWS_LOADED": 334518,
      "ROWS_READ": 334518,
      "ROWS_REJECTED": 0,
      "ROWS_SKIPPED": 0,
      "SCHEMA": "DASH123456",
      "START_TIME": "20160101 09:41:19 CST",
      "TABLE": "ORDER_DETAILS"
    },
    "resultCode": "SUCCESS"
  },
  "resultCode": "SUCCESS"
}

    Get information on load jobs based on tableName

    Get detailed information about active or completed load jobs initiated by the current user to load data into the specified table. The command will fail if there are no jobs associated with the current user that load data into the specified table.

    GET /load/{tableName}

    Request

    Path Parameters

    • tableName
      Required*
      string

      Name of the target table.

    Response

    Response Body

    LoadGetTableResponse

    Status Code

    • 200

      Ok

    • 400

      Bad Request

    • 401

      Unauthorized

    • 404

      Not Found

    • 405

      Method Not Allowed

    Example responses
    • {
  "errorMessageCode": "NONE",
  "message": "LOAD retrieved successfully",
  "result": [
    {
      "errorMessageCode": "NONE",
      "message": "Load completed successfully.",
      "result": {
        "END_TIME": "20160101 09:41:27 CST",
        "LOAD_ID": 1234567890,
        "LOAD_LOGFILE": "loadlogs/load_1234567890_DASH123456_ORDER_DETAILS_20160101-094119-CST.json",
        "LOAD_STATUS": "COMPLETE",
        "ROWS_COMMITTED": 334518,
        "ROWS_DELETED": 0,
        "ROWS_LOADED": 334518,
        "ROWS_READ": 334518,
        "ROWS_REJECTED": 0,
        "ROWS_SKIPPED": 0,
        "SCHEMA": "DASH123456",
        "START_TIME": "20160101 09:41:19 CST",
        "TABLE": "ORDER_DETAILS"
      },
      "resultCode": "SUCCESS"
    },
    {
      "errorMessageCode": "NONE",
      "message": "Load completed successfully.",
      "result": {
        "END_TIME": "20160101 09:55:03 CST",
        "LOAD_ID": 2345678901,
        "LOAD_LOGFILE": "loadlogs/load_2345678901_DASH123456_ORDER_DETAILS_20160101-095500-CST.json",
        "LOAD_STATUS": "COMPLETE",
        "ROWS_COMMITTED": 111505,
        "ROWS_DELETED": 0,
        "ROWS_LOADED": 111505,
        "ROWS_READ": 111505,
        "ROWS_REJECTED": 0,
        "ROWS_SKIPPED": 0,
        "SCHEMA": "DASH123456",
        "START_TIME": "20160101 09:55:00 CST",
        "TABLE": "ORDER_DETAILS"
      },
      "resultCode": "SUCCESS"
    }
  ],
  "resultCode": "SUCCESS"
}

    Run a temporary R script file

    Run a temporary R script file in the home directory. After the script is run the temporary file is deleted.

    Use the GET /home endpoint to find output files, and the GET /home/{filename} endpoint to retrieve output files.

    POST /rscript

    Request

    Request Body

    Required*
    rscript_bodyInput

    Percent-encoded R script.

    Response

    Response Body

    SuccessResponse

    Status Code

    • 200

      Ok

    • 400

      Bad Request

    • 401

      Unauthorized

    • 404

      Not Found

    • 405

      Method Not Allowed

    No Sample Response

    This method does not specify any sample responses.

    Run an existing R script file

    Run an R script file that is located in the home directory, such as the sample Db2 Warehouse on Cloud R scripts and scripts generated by the integrated RStudio.

    Use the GET /home endpoint to find output files, and the GET /home/{filename} endpoint to retrieve output files.

    POST /rscript/{filename}

    Request

    Path Parameters

    • filename
      Required*
      string

      The relative path of the R script file.

    Request Body

    rscript_bodyInput2

    Arguments that will be passed to the R script and readable using 'args <- commandArgs(TRUE)'.

    Response

    Response Body

    SuccessResponse

    Status Code

    • 200

      Ok

    • 400

      Bad Request

    • 401

      Unauthorized

    • 404

      Not Found

    • 405

      Method Not Allowed

    No Sample Response

    This method does not specify any sample responses.