{
  "openapi": "3.1.1",
  "info": {
    "title": "Timetable Management",
    "description": "Entur provides an API for uploading and downloading NeTEx timetable datasets. \nThese endpoints have restricted access and require a service account (OAuth2) provided by Entur.\n\n## Getting access to the API\nTo get access to the Timetable Management API, please contact Entur at kollektivdata@entur.org\nYou will be granted dedicated OAuth2 credentials (\"client-id\" and \"client-secret\") that will allow you to access the service.\n\n## Entur authentication and authorization service\n\nThe endpoints are protected by an OAuth2 authorization layer. Once you receive OAuth2 credentials, \nyou will be able to request access tokens from Entur authorization server using the following parameters:\n\n| Env     | OAuth2 token URI                              | OAuth2 audience / Base URI   |\n| ------- | --------------------------------------------- | ---------------------------- |\n| Dev     | https://partner.dev.entur.org/oauth/token     | https://api.dev.entur.io     |\n| Staging | https://partner.staging.entur.org/oauth/token | https://api.staging.entur.io |\n| Prod    | https://partner.entur.org/oauth/token         | https://api.entur.io         |\n",
    "version": "2026.06.0"
  },
  "servers": [
    {
      "url": "https://api.entur.io/timetable/v1/timetable-management",
      "description": "Production"
    },
    {
      "url": "https://api.staging.entur.io/timetable/v1/timetable-management",
      "description": "Staging"
    },
    {
      "url": "https://api.dev.entur.io/timetable/v1/timetable-management",
      "description": "Development"
    }
  ],
  "security": [
    {
      "jwt": []
    }
  ],
  "tags": [
    {
      "name": "Datasets",
      "description": "Standard timetable dataset operations"
    },
    {
      "name": "Flexible Transport",
      "description": "Flexible transport dataset operations"
    }
  ],
  "paths": {
    "/datasets/{codespace}": {
      "post": {
        "tags": [
          "Datasets"
        ],
        "summary": "Upload NeTEx dataset",
        "description": "This endpoint allows for uploading a NeTEx dataset into Entur import and validation pipeline. It provides the same feature as a manual upload from the Operator Portal application.",
        "operationId": "upload",
        "parameters": [
          {
            "name": "codespace",
            "in": "path",
            "description": "Lowercase codespace attributed to the data provider. Examples: rut, sky, vyg, …",
            "required": true,
            "style": "simple",
            "explode": false,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "multipart/form-data": {
              "schema": {
                "type": "object",
                "properties": {
                  "file": {
                    "type": "string",
                    "description": "NeTEx dataset file (ZIP archive)",
                    "contentMediaType": "application/octet-stream"
                  }
                }
              },
              "examples": {
                "dataset-upload": {
                  "summary": "Upload timetable dataset",
                  "description": "Example of uploading a NeTEx dataset ZIP file for provider RUT",
                  "value": {
                    "file": "netex-dataset-rut-2024-01-15.zip"
                  }
                }
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "description": "OK - the dataset has been received successfully (this is only a technical acknowledgement, before applying any validation rule. The dataset may be rejected further down in the validation pipeline)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/UploadResult"
                },
                "examples": {
                  "upload-success": {
                    "summary": "Successful upload",
                    "description": "Dataset upload initiated successfully, correlationId can be used to track progress",
                    "value": {
                      "correlationId": "550e8400-e29b-41d4-a716-446655440000"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized - the authorization token is missing or has expired.",
            "content": {
              "text/plain": {
                "examples": {
                  "default": {
                    "value": "User is not authenticated"
                  }
                }
              }
            }
          },
          "403": {
            "description": "Forbidden - the authorization token is present, but it does not provide sufficient privileges to perform the operation.",
            "content": {
              "text/plain": {
                "examples": {
                  "default": {
                    "value": "Access denied for codespace 'rut'"
                  }
                }
              }
            }
          },
          "404": {
            "description": "Not Found - most likely a typo in the request URL.",
            "content": {
              "text/plain": {
                "examples": {
                  "default": {
                    "value": "Unknown codespace"
                  }
                }
              }
            }
          },
          "500": {
            "description": "Internal Server Error - a processing error on Entur's side.",
            "content": {
              "text/plain": {
                "examples": {
                  "default": {
                    "value": "Internal server error"
                  }
                }
              }
            }
          }
        }
      },
      "parameters": [
        {
          "$ref": "#/components/parameters/ET-Client-Name"
        },
        {
          "$ref": "#/components/parameters/X-Correlation-Id"
        }
      ]
    },
    "/flex-datasets/{codespace}": {
      "post": {
        "tags": [
          "Flexible Transport"
        ],
        "summary": "Upload flexible transport dataset",
        "description": "Upload a NeTEx dataset containing flexible transport data",
        "operationId": "uploadFlexDataset",
        "parameters": [
          {
            "name": "codespace",
            "in": "path",
            "description": "Provider Codespace",
            "required": true,
            "style": "simple",
            "explode": false,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "multipart/form-data": {
              "schema": {
                "type": "object",
                "properties": {
                  "file": {
                    "type": "string",
                    "description": "NeTEx flex dataset file (ZIP archive)",
                    "contentMediaType": "application/octet-stream"
                  }
                }
              },
              "examples": {
                "flex-dataset-upload": {
                  "summary": "Upload flexible transport dataset",
                  "description": "Example of uploading a NeTEx flexible transport dataset ZIP file for provider FLX",
                  "value": {
                    "file": "netex-flex-dataset-flx-2024-01-15.zip"
                  }
                }
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "description": "OK - the dataset has been received successfully (this is only a technical acknowledgement, before applying any validation rule. The dataset may be rejected further down in the validation pipeline)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/UploadResult"
                },
                "examples": {
                  "flex-upload-success": {
                    "summary": "Successful flex upload",
                    "description": "Flexible transport dataset upload initiated successfully, correlationId can be used to track progress",
                    "value": {
                      "correlationId": "660f9511-f30c-52e5-b827-557766551111"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized - the authorization token is missing or has expired.",
            "content": {
              "text/plain": {
                "examples": {
                  "default": {
                    "value": "User is not authenticated"
                  }
                }
              }
            }
          },
          "403": {
            "description": "Forbidden - the authorization token is present, but it does not provide sufficient privileges to perform the operation.",
            "content": {
              "text/plain": {
                "examples": {
                  "default": {
                    "value": "Access denied"
                  }
                }
              }
            }
          },
          "404": {
            "description": "Not Found - most likely a typo in the request URL.",
            "content": {
              "text/plain": {
                "examples": {
                  "default": {
                    "value": "Not found"
                  }
                }
              }
            }
          },
          "500": {
            "description": "Internal Server Error - a processing error on Entur's side.",
            "content": {
              "text/plain": {
                "examples": {
                  "default": {
                    "value": "Internal server error"
                  }
                }
              }
            }
          }
        }
      },
      "parameters": [
        {
          "$ref": "#/components/parameters/ET-Client-Name"
        },
        {
          "$ref": "#/components/parameters/X-Correlation-Id"
        }
      ]
    },
    "/datasets/{codespace}/filtered": {
      "get": {
        "tags": [
          "Datasets"
        ],
        "summary": "Download filtered NeTEx dataset",
        "description": "This endpoint gives access to private NeTEx datasets not available on Entur open data portal.\nThese datasets include, in addition to the data available on the open data portal, the following private data:\n- NeTEx Block data\n- DeadRuns\n- Lines and Service Journeys with restricted publication\n\nThis dataset is time-filtered (past trips are removed) and content-filtered (unknown NeTEx entities are filtered out).\nDatasets that failed validation are not published on this endpoint.\nTo access the original NeTEx dataset sent by the data provider, without any alteration, \nuse instead [Latest original dataset download endpoint](https://api.entur.io/timetable/v1/timetable-data).\n",
        "operationId": "download",
        "parameters": [
          {
            "name": "codespace",
            "in": "path",
            "description": "Codespace of the NeTEx dataset",
            "required": true,
            "style": "simple",
            "explode": false,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "NeTEx dataset ZIP archive with private data. Expired data and unsupported NeTEx entities are filtered out.",
            "content": {
              "application/x-octet-stream": {
                "schema": {
                  "type": "string",
                  "contentMediaType": "application/octet-stream"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized - the authorization token is missing or has expired.",
            "content": {
              "text/plain": {
                "examples": {
                  "default": {
                    "value": "User is not authenticated"
                  }
                }
              }
            }
          },
          "403": {
            "description": "Forbidden - the authorization token is present, but it does not provide sufficient privileges to perform the operation.",
            "content": {
              "text/plain": {
                "examples": {
                  "default": {
                    "value": "Access denied"
                  }
                }
              }
            }
          },
          "404": {
            "description": "Not Found - most likely a typo in the request URL.",
            "content": {
              "text/plain": {
                "examples": {
                  "default": {
                    "value": "Not found"
                  }
                }
              }
            }
          },
          "500": {
            "description": "Internal Server Error - a processing error on Entur's side.",
            "content": {
              "text/plain": {
                "examples": {
                  "default": {
                    "value": "Internal server error"
                  }
                }
              }
            }
          }
        }
      },
      "parameters": [
        {
          "$ref": "#/components/parameters/ET-Client-Name"
        },
        {
          "$ref": "#/components/parameters/X-Correlation-Id"
        }
      ]
    }
  },
  "components": {
    "schemas": {
      "Error": {
        "required": [
          "errorCode",
          "message"
        ],
        "type": "object",
        "properties": {
          "message": {
            "type": "string",
            "description": "Human-readable error message"
          },
          "errorCode": {
            "type": "string",
            "description": "Error code identifying the type of error"
          }
        }
      },
      "UploadResult": {
        "type": "object",
        "properties": {
          "correlationId": {
            "type": "string"
          }
        }
      }
    },
    "parameters": {
      "ET-Client-Name": {
        "in": "header",
        "name": "ET-Client-Name",
        "description": "\nEntur Client Header.\nIt is required that all consumers identify themselves by using this header.\nEntur will deploy strict rate-limiting policies on API-consumers who do not identify with a header and reserves the right to block unidentified consumers.\nThe structure of ET-Client-Name should be: `<company>-<application>` for companies, and `<personal name>-<application>` for individuals.",
        "schema": {
          "type": "string"
        }
      },
      "X-Correlation-Id": {
        "in": "header",
        "name": "X-Correlation-Id",
        "description": "Correlation id",
        "schema": {
          "type": "string"
        }
      }
    },
    "securitySchemes": {
      "jwt": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "JWT"
      }
    }
  }
}