{
  "openapi": "3.0.3",
  "info": {
    "version": "1.1.0",
    "title": "DataLabel API",
    "description": "APIs exposed for DataLabel data transparency API. \nThis tool requires an IAB Tech Lab login to generate an API Bearer token. Contact IAB support to access upload features.\n\n Most APIs will require a Bearer token in the Authorization header.  DO NOT USE the Authorization generated in Swagger docs. Use these instructions to obtain an access token: [https://app-api.datalabel.org/docs/oauth](https://app-api.datalabel.org/docs/oauth).    The ENUM value and Taxonomy APIs may be accessed without a Bearer token.",
    "license": {
      "name": "MIT"
    }
  },
  "externalDocs": [{
    "description": "Instructions for obtaining an API access Bearer token",
    "url": "https://app-api.datalabel.org/docs/oauth"
  }],
  "servers": [
    {
      "url": "https://app-api.datalabel.org/api/v1",
      "description": "Production DataLabel application API server"
    },
    {
      "url": "https://app-api.datalabel.org/api/v1",
      "description": "Production DataLabel application API server"
    }
  ],
  "security":{
  	"oAuthAPISecurity": ["tagapp"]
  },
  "paths": {
    "/dimension/all": {
      "get": {
        "summary": "Obtain a Dictionary of all Enumerations used in Audience records",
        "operationId": "allEnums",
        "tags": [
          "enums"
        ],
        "responses": {
          "200": {
            "description": "Dictionary of enumerations",
            "content": {
              "application/json": {
	            "schema": {
	              "type": "string"
	            }
              }
            }
          }
        }
      }
    },
    "/taxonomy/byname": {
      "get": {
        "summary": "Fetch a specific Audience Taxonomy by its human readable name or search keyword",
        "operationId": "searchTaxonomyByName",
        "tags": [
          "taxonomy"
        ],
        "parameters": [
          {
            "name": "name",
            "in": "query",
            "required": true,
            "description": "Name or partial name string to search",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Wrapped Audience or null",
            "content": {
              "application/json": {
                "schema": null
              }
            }
          },
          "default": {
            "description": "unexpected error",
            "content": {
              "application/json": {
                "schema": null
              }
            }
          }
        }
      }
    },
    "/taxonomy/toplevel": {
      "get": {
        "summary": "Top level Audience Taxonomy categories",
        "operationId": "topLevelTaxonomy",
        "tags": [
          "taxonomy"
        ],
        "responses": {
          "200": {
            "description": "Wrapped Audience or null",
            "content": {
              "application/json": {
                "schema": null
              }
            }
          }
        }
      }
    },
    "/taxonomy/fulltree/{taxonomyId}": {
      "get": {
        "summary": "Taxonomy tree using the provided ID as the root.",
        "operationId": "taxonomyTree",
        "tags": [
          "taxonomy"
        ],
        "parameters": [
          {
            "name": "taxonomyId",
            "in": "path",
            "required": true,
            "description": "The id of the taxonomy search for.",
            "schema": {
              "type": "integer",
              "format": "int32"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Wrapped Audience or null",
            "content": {
              "application/json": {
                "schema": null
              }
            }
          }
        }
      }
    },
    "/taxonomy/parents/{taxonomyId}": {
      "get": {
        "summary": "Parent taxonomy records for the given ID. This allows you to view an uptree of the given taxonomy in the hierarchy.",
        "operationId": "taxonomyParents",
        "tags": [
          "taxonomy"
        ],
        "parameters": [
          {
            "name": "taxonomyId",
            "in": "path",
            "required": true,
            "description": "The id of the taxonomy search for.",
            "schema": {
              "type": "integer",
              "format": "int32"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Wrapped Audience or null",
            "content": {
              "application/json": {
                "schema": null
              }
            }
          }
        }
      }
    },

    "/audience/sample": {
      "get": {
        "summary": "Fetch the sample Audience as CSV or JSON. Unlike the specific ID audience that is wrapped, this is a raw file",
        "operationId": "showSampleAudience",
        "tags": [
          "audience"
        ],
        "parameters": [
          {
            "name": "Accept",
            "in": "header",
            "required": false,
            "description": "Specify one of 'application/json' or 'text/csv' to obtain a specific format. The default is CSV.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Sample Audience or null",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Audience"
                }
              },
              "text/csv": {
                "schema": {
                  "$ref": "#/components/schemas/Audience"
                }
              }
            }
          },
          "default": {
            "description": "unexpected error",
            "content": {
              "application/json": {
                  "$ref": "#/components/schemas/Error"
              }
            }
          }
        }
      }
    },
    "/audience/samplecsv": {
      "get": {
        "summary": "Fetch the sample Audience as CSV. Convenience method for CSV format. This is a raw file response",
        "operationId": "showSampleAudienceCsv",
        "tags": [
          "audience"
        ],
        "responses": {
          "200": {
            "description": "Sample Audience or null",
            "content": {
              "text/csv": {              }
            }
          },
          "default": {
            "description": "unexpected error",
            "content": {
              "application/json": {
                  "$ref": "#/components/schemas/Error"
              }
            }
          }
        }
      }
    },
    "/audience/samplejson": {
      "get": {
        "summary": "Fetch the sample Audience as JSON. Convenience method for JSON format. This is a raw file response",
        "operationId": "showSampleAudienceJson",
        "tags": [
          "audience"
        ],
        "responses": {
          "200": {
            "description": "Sample Audience or null",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Audience"
                }
              }
            }
          },
          "default": {
            "description": "unexpected error",
            "content": {
              "application/json": {
                  "$ref": "#/components/schemas/Error"
              }
            }
          }
        }
      }
    },
    "/audience/{audienceId}": {
      "get": {
        "summary": "Fetch a specific Audience",
        "operationId": "showAudienceById",
        "tags": [
          "audience"
        ],
        "parameters": [
          {
            "name": "audienceId",
            "in": "path",
            "required": true,
            "description": "The id of the audience to retrieve",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Wrapped Audience or null",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Audience"
                }
              }
            }
          },
          "default": {
            "description": "unexpected error",
            "content": {
              "application/json": {
                  "$ref": "#/components/schemas/Error"
              }
            }
          }
        }
      }
    },
    "/audience/{audienceId}/csv": {
      "get": {
        "summary": "Fetch a specific Audience as a delimited flat file",
        "operationId": "showCsvAudienceById",
        "tags": [
          "audience"
        ],
        "parameters": [
          {
            "name": "audienceId",
            "in": "path",
            "required": true,
            "description": "The id of the audience to retrieve",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "delimiter",
            "in": "query",
            "required": false,
            "description": "Specify \"t\" to use tab delimited format instead of comma delimited (csv).",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "CSV or TSV data.",
            "content": {
              "text/csv": {
                "schema": { "type": "string" }
              },
              "text/tab-separated-values": {
                "schema": { "type": "string" }
              }
            }
          }
        }
      }
    },

    "/audiences/alldata/{format}": {
      "get": {
        "summary": "Download all Audience Segment data. Default format is CSV",
        "operationId": "downloadAllAudienceData",
        "tags": [
          "audience"
        ],
        "parameters": [
          {
            "name": "format",
            "in": "path",
            "required": false,
            "description": "CSV or JSON data using values 'csv' and 'json', respectively",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "linkonly",
            "in": "query",
            "required": false,
            "description": "When a value of \"true\" is added, a JSON representation of file location and size is returned instead of a redirect.",
            "schema": {
              "type": "boolean"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "CSV or JSON data.",
            "content": {
              "text/csv": {
                "schema": { "type": "string" }
              },
              "text/tab-separated-values": {
                "schema": { "type": "string" }
              }
            }
          }
        }
      }
    },

    "/audiences": {
      "get": {
        "summary": "List all Audiences",
        "operationId": "listAudiences",
        "tags": [
          "audiences"
        ],
        "responses": {
          "200": {
            "description": "Wrapper with an array of Audiences",
            "headers": {
              "x-next": {
                "description": "A link to the next page of responses",
                "schema": {
                  "$ref": "./schema/audience-schema-v1.1.json#Audience"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "schema/audience-schema-v1.1.json#Audience"
                }
              }
            }
          },
          "default": {
            "description": "unexpected error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      },
      "put" : {
        "summary": "Upload delimited flat file of Audience records",
        "operationId": "uploadAudiences",
        "tags": [
          "audiences",
          "upload"
        ],
        "parameters":[
	        {
	        	"in": "header",
	        	"name": "Content-Type",
	        	"description": "The content type header describes the format of the file being submitted. The default format is assumed to be 'text/csv'",
	        	"required": false,
	        	"schema": {
	              "type": "string"
	            }
	        }
        ],
        "requestBody" :{
        	"description": "Flat file of audience(s)",
        	"required": true,
        	"content": {
        		"multipart/form-data" : {
        			"schema" :{
        				"type": "object",
        				"properties":{
        					"file": {
        						"type": "string",
       							"format": "text/csv",
       							"required": true
        					},
        					"keepPrevious":{
        						"type": "boolean",
        						"required": false,
        						"description": "Flag to keep previously uploaded audiences, or delete all previous audiences (default behavior)."    						
        					}
        				}
        			}
        		}        		
        	}
        },
        "responses": {
          "200": {
            "description": "Wrapper with summary of result of upload process",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Audience"
                }
              }
            }
          }
        }
      }
    },
    "/audiences/test": {
      "put" : {
        "summary": "Upload for testing a delimited flat file of Audience records",
        "operationId": "uploadTestAudiences",
        "tags": [
          "audiences",
          "upload"
        ],
        "parameters":[
	        {
	        	"in": "header",
	        	"name": "Content-Type",
	        	"description": "The content type header describes the format of the file being submitted. The default format is assumed to be 'text/csv'",
	        	"required": false,
	        	"schema": {
	              "type": "string"
	            }
	        }
        ],
        "requestBody" :{
        	"description": "Flat file of audience(s)",
        	"required": true,
        	"content": {
        		"multipart/form-data" : {
        			"schema" :{
        				"type": "object",
        				"properties":{
        					"file": {
        						"type": "string",
       							"format": "text/csv",
       							"required": true
        					},
        					"keepPrevious":{
        						"type": "boolean",
        						"required": false,
        						"description": "Flag to keep previously uploaded audiences, or delete all previous audiences (default behavior)."    						
        					}
        				}
        			}
        		}        		
        	}
        },
        "responses": {
          "200": {
            "description": "Wrapper with summary of result of upload process",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Audience"
                }
              }
            }
          }
        }
      }
    },
    "/audiences/provider/{providerId}": {
      "get": {
        "summary": "List all Audiences grouped by provider",
        "operationId": "listAudiencesFromProvider",
        "tags": [
          "audiences"
        ],
        "parameters": [
          {
            "name": "providerId",
            "in": "path",
            "required": true,
            "description": "The id of the audience to retrieve",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "description": "How many items to return at one time (max 100)",
            "required": false,
            "schema": {
              "type": "integer",
              "format": "int32"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Wrapper with a dictionary of Audiences keyed off Provider",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Audience"
                }
              }
            }
          },
          "default": {
            "description": "unexpected error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/audiences/byprovider": {
      "get": {
        "summary": "List all Audiences grouped by provider",
        "operationId": "listAudiencesByProvider",
        "tags": [
          "audiences"
        ],
        "parameters": [
          {
            "name": "limit",
            "in": "query",
            "description": "How many items to return at one time (max 100)",
            "required": false,
            "schema": {
              "type": "integer",
              "format": "int32"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Wrapper with a dictionary of Audiences keyed off Provider",
            "headers": {
              "x-next": {
                "description": "A link to the next page of responses",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Audience"
                }
              }
            }
          },
          "default": {
            "description": "unexpected error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Audience"
                }
              }
            }
          }
        }
      }
    },
    "/audiences/mine": {
      "get": {
        "summary": "List all Audiences owned by the Company of the current user",
        "operationId": "listOwnedAudiences",
        "tags": [
          "audiences"
        ]
      },
      "delete": {
        "summary": "Delete all Audiences owned by the Company of the current user",
        "operationId": "deleteOwnedAudiences",
        "tags": [
          "audiences"
        ]
      }
    },
    "/audiences/bytaxonomy": {
      "get": {
        "summary": "List all Audiences grouped by standard name Audience Taxonomy",
        "operationId": "listAudiencesByTaxonomy",
        "tags": [
          "audiences"
        ],
        "parameters": [
          {
            "name": "limit",
            "in": "query",
            "description": "How many items to return at one time (max 100)",
            "required": false,
            "schema": {
              "type": "integer",
              "format": "int32"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Wrapper with a dictionary of Audiences keyed off Audience Taxonomy",
            "headers": {
              "x-next": {
                "description": "A link to the next page of responses",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Audience"
                }
              }
            }
          },
          "default": {
            "description": "unexpected error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    }
  },
  "components":{
  	"securitySchemes": {
  		"oAuthAPISecurity": {
  			"type": "oauth2",
  			"description": "Standard OAuth flow to obtain a Bearer access token for API access",
  			"flows":{
  				"authorizationCode": {
  					"authorizationUrl": "https://api.iabtechlab.com/oauth/authorize"
  				},
  				"password": {
  					"tokenUrl": "https://api.iabtechlab.com/oauth/authorize"
  				}  				
  			}
  		}
  	},
  	"schemas":{
  		"Audience":{
		    "type": "object",
		    "title": "Audience Schema"
  		},
  		"Error":{
		    "type": "object",
		    "title": "Error Schema"
  		}
  	}
  }
}