Interrogation data formatted in the M5 File format can be submitted from M5, I5 or by using the PTAGIS web API. The API includes two endpoints (load and remove) for submitting M5 files in a RESTful manner.

 

To submit files using the PTAGIS API, data contributors will need to do the following:

1.Contact PTAGIS to obtain an API key used for authorization.

2.Build a properly formatted M5 file.

3.Use the /submissions/interrogation/authorize endpoint to request authorization to submit a file (described below).

4.Use the JSON web token (JWT) returned from the call in #3 with the appropriate /submissions/interrogation endpoint to either load or remove the file (see sample code).

5.Use the /submissions/interrogation/{id} endpoint with the Submission ID to request the status of the file after it has processed.

 

If you plan to build an application to submit M5 files using the web API, you should use the Test API (https://testapi.ptagis.org) while developing and testing the application. Files submitted using the Test API will be processed using the test system and will not be loaded into the production database.

 

The /submissions/interrogation/authorize call requires the following in the request body:

•API Key: a GUID assigned to you (contact PTAGIS to receive one)

•Site Code: the interrogation site for which data will be submitted

•Registered Email Address: an email address registered with PTAGIS and allowed to submit data for that site

 

Sample Code

The following C# sample code shows how to include the JWT returned from the authorize endpoint in the subsequent call to submit the data to PTAGIS.

 

 

  using System;

  using System.IO;

  using System.Net.Http;

  using System.Net.Http.Headers;

  using System.Threading.Tasks;

 

  class Program

  {

      static async Task Main()

      {

          //NOTE: using test API endpoint

          var apiUrl = "https://testapi.ptagis.org/submissions/interrogation/load";

          var jwtToken = "your_jwt_token_here";

          var m5FilePath = "path/to/your/M5/file/TST-2025-120-002.json";

 

          using var httpClient = new HttpClient();

 

          // Add the JWT token to the Authorization header

          httpClient.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", jwtToken);

 

          // Prepare the multipart form data content

          using var form = new MultipartFormDataContent();

          using var fileStream = File.OpenRead(m5FilePath);

          var fileContent = new StreamContent(fileStream);

          fileContent.Headers.ContentType = new MediaTypeHeaderValue("application/json");

           

          // Add the file content to the form data

          form.Add(fileContent, "file", Path.GetFileName(m5FilePath));

 

          // Send the POST request

          var response = await httpClient.PostAsync(apiUrl, form);

 

          if (response.IsSuccessStatusCode)

          {

              Console.WriteLine("JSON file uploaded successfully!");

              var result = await response.Content.ReadAsStringAsync();

              Console.WriteLine(result);

          }

          else

          {

              Console.WriteLine($"Upload failed: {response.StatusCode}");

              var error = await response.Content.ReadAsStringAsync();

              Console.WriteLine(error);

          }

      }

  }

 

File Load Status Response

Interrogation files that do not meet format specifications will generate a Bad Request (400) response when submitted via the web API with content such as:

 

{​​​​​​ "type": "https://tools.ietf.org/html/rfc7231#section-6.5.1",

  "title": "One or more validation errors occurred.",

  "status": 400,

  "traceId": "00-53c04c6850137344bbc33307a7857618-559a719db20ca44c-00",

  "errors": {​​​​​​

    "SystemDescription": [ "The SystemDescription field is required." ],

    "InterrogationFieldData[1537].FieldData":

        [ "The field FieldData must be a string or array type with a maximum length of '500'." ]

    }​​​​​​​​​​​​

​}​​​​​​​​​​​​​

 

After the file is accepted for processing, the submissions/interrogation/{id} endpoint can be used to request the status of the file. Possible responses are shown below: