openapi: 3.0.0
info:
  title: Import API
  description: >
    # Introduction

    The CARTO Import API allows you to upload files to a CARTO account, 
    check on their current upload status, as well as delete and list importing 
    processes on a given account. This API consists of several HTTP requests targeted 
    at a set of CARTO endpoints that deal with the conversion and import of the sent files. 
    CARTO tables can be classified as Standard Tables or Sync Tables. Additionally, 
    the ArcGIS Server™ Connector enables you to import ArcGIS™ layers into your datasets.

    # Authorization

    In order to access Maps API you must provide an API key. The CARTO
    Authorization guide explains how these keys are sent (TLDR: _HTTP basic
    auth_ or _query string param_ with the API key token). Depending on the
    permissions granted to the provided API key, the request will be authorized
    or not.
  version: 0.0.1
  contact:
    name: Have you found an error? Github issues
    url: 'https://github.com/CartoDB/Windshaft-cartodb/issues'
servers:
  - url: 'https://{user}.{domain}/api'
    description: Production server (uses live data)
    variables:
      domain:
        default: carto.com
        description: 'If on premise, change it to your domain'
      user:
        default: username
        description: Your username
tags:
  - name: Standard Tables
    description: Store data you upload from files creating tables at CARTO
    externalDocs:
      url: 'http://doc.carto.com/pet-operations.htm'
  - name: CARTO Map Visualizations
    description: Download a map, and the connected dataset, as a .carto file
    externalDocs:
      url: 'http://doc.carto.com/pet-operations.htm'
  - name: Sync Tables
    description: Store data from a remote file and refresh their contents during periodic intervals
    externalDocs:
      url: 'http://doc.carto.com/pet-operations.htm'
paths:
  '/v1/imports':
    post:
      summary: Create import
      description: |
        Upload File
      tags:
        - Standard Tables
      operationId: createImport
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateImport'
            examples:
              url:
                $ref: '#/components/examples/CreateImportUrl'
      responses:
        '200':
          description: Ok
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RequestResponse'
              example:
                item_queue_id: 9906bce0-f1a3-4b07-be71-818f4bfd7673
                success: true
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
      security:
        - ApiKeyHTTPBasicAuth: []
        - ApiKeyQueryParam: []
      x-code-samples:
        - lang: Curl
          source: |
            curl -v -F file=@/path/to/local/file "https://{account}
            .carto.com/api/v1/imports/?api_key={account API Key}"
    get:
      summary: List current import processes
      description: Lists the import identifiers of the files that are being imported in the targeted CARTO account
      tags:
        - Standard Tables
      operationId: getImports
      responses:
        '200':
          description: Ok
          content:
            application/json:
              schema:
                type: object
                properties:
                  imports:
                    type: array
                    description: A list of unique alphanumeric identifiers referencing the import processes in the targeted CARTO account
                    items:
                      type: string
                  success:
                    type: boolean
                    description: A boolean value indicating if the request was successful
              example:
                imports:
                  - "1234abcd-1234-1a2b-3c4d-4321dcba5678"
                success: true
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
      security:
        - ApiKeyHTTPBasicAuth: []
        - ApiKeyQueryParam: []
      x-code-samples:
        - lang: Curl
          source: >
            curl -v "https://{account}.carto.com/api/v1/imports/?api_key={account API Key}"
  '/v1/imports/{import_id}':
    get:
      parameters:
        - in: path
          name: import_id
          description: A unique alphanumeric element that identifies the import process to be retrieved. It is the `item_queue_id` element returned after running the upload request successfully.
          schema:
            type: string
          required: true
      summary: Check import status
      description: |
        Returns the Import's status and its associated metadata.
      tags:
        - Standard Tables
      operationId: getImportStatus
      responses:
        '200':
          description: Ok
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ImportStatusResponse'
              example:
                id: 029a6053-b2fb-43dd-baa6-805d679c404f
                user_id: ca8c5ace-d573-450b-8a43-6c7eafadd80e
                table_id: null
                data_type: url
                table_name: null
                state: failure
                error_code: 1002
                queue_id: 029a6053-b2fb-43dd-baa6-805d679c404f
                tables_created_count: null
                synchronization_id: null
                type_guessing: true
                quoted_fields_guessing: true
                content_guessing: false
                create_visualization: false
                visualization_id: null
                user_defined_limits: '{twitter_credits_limit:0}'
                get_error_text:
                  title: Unsupported/Unrecognized file type
                  what_about: 'Should we support this filetype? Let us know in our <a href=''mailto:support@carto.com''>support email</a>!'
                  source: user
                display_name: shapefile_streets.cpg
                success: false
                warnings: null
                is_raster: false
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
      security:
        - ApiKeyHTTPBasicAuth: []
        - ApiKeyQueryParam: []
      x-code-samples:
        - lang: Curl
          source: >
            curl -v "https://{account}.carto.com/api/v1/imports/{import_id}?api_key={account API Key}
  '/v3/visualization_exports':
    post:
      summary: Export as .carto file
      description: |
        The Export map option enables you to download a map, 
        and the connected dataset, as a .carto file. This .carto
        file includes the dataset and visualization definition,
        which contains any SQL queries, CartoCSS, basemaps,
        attributions, metadata, and styling that was applied to a
        map. This is useful for downloading complete CARTO
        visualizations that you can share or import.

        Note: The Import API export visualization command only works for maps created from `Your maps` dashboard.
      tags:
        - CARTO Map Visualizations
      operationId: exportCarto
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ExportCarto'
            example:
              visualization_id: 'ace62506-brc8-6570-2p91-8vf3af3ftc44'
                
      responses:
        '200':
          description: Ok
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExportCartoResponse'
              example:
                id: 'b94c26f3-fa16-4f13-b672-45ebbd5a9c95'
                visualization_id: 'ace62506-brc8-6570-2p91-8vf3af3ftc44'
                user_id: '42b78090-6a11-475a-8060-0a90322752af2b'
                state: 'pending'
                url: null
                created_at: '2016-05-05T09:36:09+00:00'
                updated_at: '2016-05-05T09:36:09+00:00'
                
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
      security:
        - ApiKeyHTTPBasicAuth: []
        - ApiKeyQueryParam: []
      x-code-samples:
        - lang: Curl
          source: |
            curl -v -H 'Content-Type: application/json' https://{username}.carto.com/api/v3/visualization_exports\?api_key\={api_key} -X POST --data '{"visualization_id":"9a0f4384-afe3-412a-8b09-136b7d9a4013"}'
  '/v3/visualization_exports/{visualization_export_id}':
    get:
      parameters:
        - in: path
          name: visualization_export_id
          description: A unique alphanumeric element that identifies the export process to be retrieved. It is the `id` element returned after running the export request successfully.
          schema:
            type: string
          required: true
      summary: Check .carto export status
      description: |
        After making the POST request to create the export, it is expected that the request will take some time. You must poll the server by making a GET request, until state becomes complete. Once completed, the response status changes to `complete` and displays the upload url location of the .carto visualization file
      tags:
        - CARTO Map Visualizations
      operationId: getExportStatus
      responses:
        '200':
          description: Ok
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExportCartoResponse'
              example:
                id: 'b94c26f3-fa16-4f13-b672-45ebbd5a9c95'
                visualization_id: 'ace62506-brc8-6570-2p91-8vf3af3ftc44'
                user_id: '42b78090-6a11-475a-8060-0a90322752af2b'
                state: 'complete'
                url: '/uploads/6a2b6fbd86e2c750160a/ace62506-brc8-6570-2p91-8vf3af3ftc44.carto'
                created_at: '2016-05-05T09:36:09+00:00'
                updated_at: '2016-05-05T09:36:13+00:00'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
      security:
        - ApiKeyHTTPBasicAuth: []
        - ApiKeyQueryParam: []
      x-code-samples:
        - lang: Curl
          source: >
            curl -v "https://{account}.carto.com/api/v1/imports/{import_id}?api_key={account API Key}
  '/v1/synchronizations':
    get:
      summary: List current sync tables
      description: List current sync tables
      tags:
        - Sync Tables
      operationId: getSyncTables
      responses:
        '200':
          description: Ok
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListSyncTablesResponse'
              example:
                synchronizations:
                - id: 246dae5e-5302-1ae5-af51-0e85ad047bba
                  name: barrios_5
                  interval: 2592000
                  url: https://common-data.carto.com/api/v2/sql?q=select+*+from+%22barrios%22&format=shp&filename=barrios
                  state: success
                  created_at: '2015-09-04T12:40:37+00:00'
                  updated_at: '2016-02-01T12:45:07+00:00'
                  run_at: '2016-03-02T12:45:07+00:00'
                  retried_times: 0
                  log_id: 2d9b4a52-1daa-429b-b425-6ad561609cb1
                  error_code: null
                  error_message: null
                  ran_at: '2016-02-01T12:45:07+00:00'
                  modified_at: '2015-04-22T12:17:50+00:00'
                  etag: null
                  checksum: null
                  user_id: cf8a5cce-d573-4a0b-8c43-6caeaf1dd80e
                  service_name: null
                  service_item_id: https://common-data.carto.com/api/v2/sql?q=select+*+from+%22barrios%22&format=shp&filename=barrios
                  type_guessing: true
                  quoted_fields_guessing: true
                  content_guessing: true
                  visualization_id: 2954fa60-5a02-11e5-888a-0e5e07bb5d8a
                  from_external_source: false
                total_entries: 1
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
      security:
        - ApiKeyHTTPBasicAuth: []
        - ApiKeyQueryParam: []
      x-code-samples:
        - lang: Curl
          source: >
            curl -v "https://{username}.carto.com/api/v1/synchronizations/?api_key={account API Key}"
    post:
      summary: Sync a file from a URL
      description: |
        Desc
      tags:
        - Sync Tables
      operationId: syncTable
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateSyncTablesPayload'
            example:
              url: 'https://public.url.to.file/sample_file'
              interval: 3600
                
      responses:
        '200':
          description: Ok
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateSyncTablesResponse'
              example:
                  data_import:
                    endpoint: "/api/v1/imports"
                    item_queue_id: 1234abcd-1234-1a2b-3c4d-4321dcba5678
                  id: abcd1234-a5b6-c7d8-1a2b-efgh5678abcd
                  name: null
                  interval: 3600
                  url: https://public.url.to.file/sample_file
                  state: created
                  user_id: aaaabbbb-1234-5678-dcba-abcd1234efgh
                  created_at: '2014-08-05T13:39:15+00:00'
                  updated_at: '2014-08-05T13:39:15+00:00'
                  run_at: '2014-08-05T14:39:15+00:00'
                  ran_at: '2014-08-05T13:39:15+00:00'
                  modified_at: null
                  etag: null
                  checksum: ''
                  log_id: 06fafab8-3502-11e4-9514-0e230854a1cb
                  error_code: null
                  error_message: null
                  retried_times: 0
                  service_name: null
                  service_item_id: null
                  type_guessing: true
                  quoted_fields_guessing: true
                  content_guessing: false
                  visualization_id: null
                  from_external_source: false
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
      security:
        - ApiKeyHTTPBasicAuth: []
        - ApiKeyQueryParam: []
      x-code-samples:
        - lang: Curl
          source: |
            curl -v -H "Content-Type: application/json" -d '{"url":"https://public.url.to.file/sample_file", "interval":"3600"}' "https://{username}.carto.com/api/v1/synchronizations/?api_key={account API Key}"
  '/v1/synchronizations/{import_id}':
    delete:
      summary: Remove sync feature from table
      description: A sync table can be converted to a standard dataset (a dataset that never gets synced)
      tags:
        - Sync Tables
      operationId: removeSyncTables
      parameters:
        - in: path
          name: import_id
          description: The unique alphanumeric identifier of the target sync dataset
          schema:
            type: string
          required: true
      responses:
        '204':
          description: No content
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
      security:
        - ApiKeyHTTPBasicAuth: []
        - ApiKeyQueryParam: []
      x-code-samples:
        - lang: Curl
          source: >
            curl -v -X "DELETE" https://{username}.carto.com/api/v1/synchronizations/{import_id}?api_key={account API Key}"
  '/v1/synchronizations/{import_id}/sync_now':
    get:
      summary: Check whether a sync table is syncing or not
      description: A large synced table may take some time to get fully synced. In the meantime, it could be useful to check whether it finished refreshing its contents
      tags:
        - Sync Tables
      operationId: checkSyncTables
      parameters:
        - in: path
          name: import_id
          description: The unique alphanumeric identifier of the target sync dataset
          schema:
            type: string
          required: true
      responses:
        '200':
          description: Ok
          content:
            application/json:
              schema:
                type: object
                properties:
                  state:
                    type: string
                    enum:
                      - created
                      - queued
                      - syncing
                      - success
                      - failure
                    title: State
                    description: A string value indicating the status of the synchronization
              example:
                  state: syncing
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
      security:
        - ApiKeyHTTPBasicAuth: []
        - ApiKeyQueryParam: []
      x-code-samples:
        - lang: Curl
          source: >
            curl -v -X "GET" "https://{username}.carto.com/api/v1/synchronizations/{import_id}/sync_now?api_key={account API Key}"
    put:
      summary: Force a synchronization action on a sync table
      description: |
        Sync tables have their contents synchronized with the source file in periodic time intervals as specified by the user during the creation process. However, a dataset can be synchronized at an arbitrary moment in time if desired. Note: Forcing a synchronization can only be performed when the last synchronization attempt occurred at least 900 seconds (15 minutes) before.
      tags:
        - Sync Tables
      operationId: forceSyncTable
      parameters:
        - in: path
          name: import_id
          description: The unique alphanumeric identifier of the target sync dataset
          schema:
            type: string
          required: true
      responses:
        '200':
          description: Ok
          content:
            application/json:
              schema:
                type: object
                properties:
                  enqueued:
                    type: boolean
                    title: Enqueued
                    description: A boolean value indicating whether the request has been successfully appended to the processing queue
                  synchronization_id  :
                    type: string
                    title: Synchronization ID
                    description: A unique alphanumeric identifier referring to the queue element just added
              example:
                enqueued: false
                synchronization_id: "1234abcd-aaaa-2222-4444-dcba4321a1b2"
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
      security:
        - ApiKeyHTTPBasicAuth: []
        - ApiKeyQueryParam: []
      x-code-samples:
        - lang: Curl
          source: |
            curl -v -X "PUT" "https://{username}.carto.com/api/v1/synchronizations/<import_id>/sync_now?api_key={account API Key}" -H "Content-Length:0"
components:
  schemas:
    CreateImport:
      type: object
      properties:
        file:
          $ref: '#/components/schemas/File'
        url:
          $ref: '#/components/schemas/Url'
        type_guessing:
          type: boolean
          default: true
          title: Type guessing
          description:   If set to `false` disables field type guessing (for Excel and CSVs)
        quoted_fields_guessing:
          type: boolean
          default: false
          title: Quoted fields guessing
          description:   If set to `false` disables type guessing of CSV fields that come inside double quotes
        content_guessing:
          type: boolean
          default: false
          title: Content guessing
          description:   Set to `true` to enable content guessing and automatic geocoding based on results. Currently, this only implements geocoding of countries, cities and IP addresses
        create_vis:
          type: boolean
          default: false
          title: Create Vis
          description:   Set to `true` to flag the import so that when it finishes, it creates a Map automatically after importing the Dataset
        collision_strategy:
          type: string
          enum:
            - skip
            - overwrite
          title: Collision strategy
          description: > 
            Determines the behavior when importing a dataset 
            that has the same name as an existing table. By default,
            it is imported and renamed with a sequential number
            (*mytable*, *mytable_1*…).
            
            - `skip`: the table with the
            matching name will not be imported.
            
            - `overwrite`: it will replace
            the table with the matching name, but only if the new
            dataset table includes the same columns and data types as
            the original table. The new table can also include
            additional columns, but not fewer than the original table. 
        privacy:
          type: string
          enum:
            - public
            - private
            - link
          title: Collision strategy
          description: > 
              Used to set the privacy settings of the table or
              tables resulting from the import.
              If `create_vis` is set to true, the resulting
              visualization privacy settings will also be 
              determined by this parameter. 
              
              `privacy` can be set to:
            
              - `public`: The resulting table or visualization can be viewed by anyone
              
              - `private`: The resulting table or visualization can only be viewed by the uploader
              
              - `link`: The resulting table or visualization can only be viewed through a private link shared by the uploader
        table_name:
          type: string
          title: Table name
          description:   Used to duplicate one of your existing tables. **Do not mix with File/URL imports**
        sql:
          type: string
          title: SQL
          description:   Used to create a new table from a SQL query applied to one of your tables. **Do not mix with File/URL imports**
    File:
      type: string
      title: file
      description: When importing local files, you need to perform a POST with a file 
    Url:
      type: string
      title: url
      description: When importing remote files, the full URL to the publicly accessible file
    RequestResponse:
      type: object
      properties:
        item_queue_id:
          type: string
          description: A unique alphanumeric identifier referencing the import process in the targeted account
        success:
          type: boolean
          description: A boolean value indicating whether the import process was started or not.
    ImportStatusResponse:
      type: object
      properties:
        id:
          type: string
          title: ID
          description: A unique identifier for the import process. It is the same as the `import_id` provided in the request
        user_id:
          type: string
          title: User ID
          description: A unique alphanumeric element that identifies the CARTO account user in the internal database
        table_id:
          type: string
          title: Table ID
          description:   A unique alphanumeric element that identifies the created table in the internal CARTO database
        data_type:
          type: string
          enum:
            - file
            - url
            - external_table
            - query
            - table
            - datasource
          title: Data type
          description: This element identifies the service type used to import the file
        table_name:
          type: string
          title: Table name
          description: The final name of the created table in the targeted CARTO account. It usually has the same name as the uploaded file, unless there already exists a table with the same name (in this case, an integer number is appended to the table name)
        status:
          type: string
          enum:
            - enqueued
            - pending
            - uploading
            - unpacking
            - importing
            - guessing
            - complete
            - failure   
          title: State
          description: A string value indicating the current state of the importing process
        error_code:
          type: number
          title: Error code
          description: A number corresponding to the error code in case of failure during the import process, that is, when the `success` item has a `false` value
        queue_id:
          type: string
          title: Queue ID
          description:  A unique identifier for the import process in the importing queue. It is the same as the `import_id` provided in the request
        tables_created_count:
          type: number
          title: Tables created counter
          description: The number of tables that the import process generated. For multi-file uploads, this value can be greater than one
          nullable: true
        synchronization_id:
          type: string
          title: Synchronization ID
          description: This element has a `null` value when the import is not configured as a Sync Table
          nullable: true
        type_guessing:
          type: boolean
          title: Type guessing
          description: A boolean indicating whether field type guessing (for Excel and CSVs) is enabled or not
        quoted_fields_guessing:
          type: boolean
          title: Quoted fields guessing
          description: A boolean indicating whether type guessing of CSV fields inside double quotes is enabled for the data import
        content_guessing:
          type: boolean
          title: Content guessing
          description: A boolean indicating whether content guessing and automatic geocoding is enabled for the data import
        create_visualization:
          type: boolean
          title: Create visualization
          description:   A boolean indicating whether the import process will create a map automatically or not. Its value corresponds to the import option `create_vis` chosen by the user
        visualization_id:
          type: string
          title: Visualization ID
          description: A unique identifier for the map created in the import process. Only applies if `created_visualization` is set to `true`
          nullable: true
        get_error_text:
          type: string
          title: Get error text
          description: This element contains an error description to be outputted in case of a failure during the import process. It contains the error title and description, its source (`user` or `cartodb`), and troubleshooting details
        display_name:
          type: string
          title: Display name
          description: Similar to `table_name`. For `url` uploads, it shows the name of the file. Otherwise, it shows the `import_id`
        success:
          type: boolean
          title: Success
          description: A boolean value indicating whether the import process succeeded
        warnings:
          type: string
          title: Warnings
          description: A text field containing warning messages related to the import process, if applicable of the file. Otherwise, it shows the `import_id`
          nullable: true
        is_raster:
          type: boolean
          title: Is raster
          description: A boolean value indicating whether the imported table contains raster data or not
    ExportCarto:
      type: object
      properties:
        visualization_id:
          type: string
          title: Visualization ID
          description: A unique identifier for the map created in the export process. Only applies if `created_visualization` is set to `true` when the map was created. 
    ExportCartoResponse:
      type: object
      properties:
        id:
          type: string
          title: ID
          description: A unique identifier for the export process. It is the same as the _export id_ provided in the request
        visualization_id:
          type: string
          title: Visualization ID
          description: A unique identifier for the map created in the export process. Only applies if `created_visualization` is set to `true` when the map was created
        user_id:
          type: string
          title: User ID
          description: A unique alphanumeric element that identifies the CARTO account user in the internal database
        state:
          type: string
          enum:
            - enqueued
            - pending
            - uploading
            - unpacking
            - importing
            - guessing
            - complete
            - failure 
          title: State
          description: A string value indicating the current state of the export process
        url:
          type: string
          title: URL
          description: The **public** URL address where the file to be exported is located
          nullable: true
        created_at:
          type: string
          format: date-time
          title: Created at
          description: The date time at which the visualization was created in the CARTO database
        updated_at:
          type: string
          format: date-time
          title: Updated at
          description: The date time at which the visualization had its contents modified
    SyncTablesResponseItem:
      type: object
      properties:
        id:
          type: string
          title: ID
          description: A unique alphanumeric identifier of the synced table
        name:
          type: string
          title: Name
          description: The actual name of the created sync table
        interval:
          type: integer
          title: Interval
          description: An integer value representing the number of seconds between synchronizations of the table contents
        url:
          type: string
          title: URL
          description: The **public** URL address where the file to be synchronized is located
          nullable: true
        state:
          type: string
          enum:
            - created
            - queued
            - syncing
            - success
            - failure
          title: State
          description: A string value indicating the current state of the synchronized dataset
        created_at:
          type: string
          format: date-time
          title: Created at
          description: The date time at which the table was created in the CARTO database
        updated_at:
          type: string
          format: date-time
          title: Updated at
          description: The date time at which the table had its contents modified
        run_at:
          type: string
          format: date-time
          title: Run at
          description: The date time at which the table **will** get its contents synched with the source file
        retried_times:
          type: integer
          title: Retried times
          description: An integer value indicating the number of attempts that were performed to sync the table
        log_id:
          type: string
          title: Log ID
          description: A unique alphanumeric identifier to locate the log traces of the given table
        error_code:
          type: integer
          title: Error code
          description: An integer value representing a unique error identifier
          nullable: true
        error_message:
          type: string
          title: Error message
          description: A string value indicating the message related to the _error_code_ element
          nullable: true
        ran_at:
          type: string
          format: date-time
          title: Ran at
          description: The date time at which the table **had** its contents synched with the source file
        modified_at:
          type: string
          format: date-time
          title: Modified at
          description: The date time at which the table was manually modified, if applicable
        etag:
          type: string
          title: ETAG
          description: HTTP entity tag of the source file
          nullable: true
        checksum:
          type: string
          title: Checksum
          description: See **etag**
          nullable: true
        user_id:
          type: string
          title: User ID
          description: A unique alphanumeric element that identifies the CARTO account user in the internal database
        service_name:
          type: string
          enum:
            - gdrive
            - dropbox
          title: State
          description: |
            A string with the name of the datasource used to import the file
            It can have any of the following values: 
            - **gdrive** - Google Drive
            - **dropbox** - Dropbox
            - `null` - URL imports
          nullable: true
        service_item_id:
          type: string
          title: Service item ID
          description: A unique identifier used by CARTO to reference the sync table and its related datasource service
        type_guessing:
          type: boolean
          title: Type guessing
          description:   If set to `false` disables field type guessing (for Excel and CSVs)
        quoted_fields_guessing:
          type: boolean
          title: Quoted fields guessing
          description:   If set to `false` disables type guessing of CSV fields that come inside double quotes
        content_guessing:
          type: boolean
          title: Content guessing
          description:   Set to `true` to enable content guessing and automatic geocoding based on results. Currently, this only implements geocoding of countries, cities and IP addresses
        visualization_id:
          type: string
          title: Visualization ID
          description: A unique identifier for the map created in the import process. Only applies if created_visualization is set to `true`
        from_external_source:
          type: boolean
          title: From external source
          description: A boolean indicating whether the Sync Table is connected to an external source, generally the CARTO Data library
    ListSyncTablesResponse:
      type: object
      properties:
        syncronizations:
          type: array
          items:
            $ref: '#/components/schemas/SyncTablesResponseItem'
        total_entries:
          type: integer
          title: Total entries
          description: Number of items contained in the response array
    CreateSyncTablesPayload:
      type: object
      properties:
        url:
          type: string
          title: URL
          description: The **public** URL address where the file to be imported is located
        interval:
          type: integer
          title: Interval
          minimum: 900
          description: 'The number of seconds for the synchronization period. Note: Sync interval must be at least 900 (15 minutes)'
        type_guessing:
          type: boolean
          title: Type guessing
          default: true
          description:   If set to `false` disables field type guessing (for Excel and CSVs)
        quoted_fields_guessing:
          type: boolean
          title: Quoted fields guessing
          default: true
          description:   If set to `false` disables type guessing of CSV fields that come inside double quotes
        content_guessing:
          type: boolean
          title: Content guessing
          default: false
          description:  Set to `true` to enable content guessing and automatic geocoding based on results. Currently, this only implements geocoding of countries, cities and IP addresses
    CreateSyncTablesResponse:
      allOf:
        - type: object
          properties:
            data_import:
              type: object
              properties:
                endpoint:
                  type: string
                  title: Endpoint
                  description: This item refers to the internal CARTO controller code responsible for performing the import
                item_queue_id:
                  type: string
                  title: Item queue ID
                  description: A unique alphanumeric identifier that refers to the import process. It can be used to retrieve data related to the created table
        - $ref: '#/components/schemas/SyncTablesResponseItem'
          
  securitySchemes:
    ApiKeyHTTPBasicAuth:
      type: http
      scheme: basic
    ApiKeyQueryParam:
      type: apiKey
      in: header
      name: api_key
  examples:
    CreateImportUrl:
      value:
        url: https://remotehost.url/path/to/remotefile
      summary: Import from URL
    RequestResponseSuccess:
      value:
        item_queue_id: 9906bce0-f1a3-4b07-be71-818f4bfd7673
        success: true
      summary: A success response  
  responses:
    NotFound:
      description: The specified resource was not found
    Unauthorized:
      description: Unauthorized. No authentication provided.
    Forbidden:
      description: Forbidden. The API key does not authorize this request.
    BadInput:
      description: Request's parameters error