Skip to main content

Internet-Draft submission API instructions

A simplified Internet-Draft submission interface, intended for automation, is available at /api/submission.

The interface accepts only XML uploads that can be processed on the server, and requires the user to have a datatracker account. A successful submit still requires the same email confirmation round-trip as submissions done through the regular submission tool.

This interface does not provide all the options which the regular submission tool does. Some limitations:

  • Only XML-only uploads are supported, not text or combined.
  • The server expects multipart/form-data, supported by curl but not by wget.

It takes the following parameters:

  • user which is the user login (required)
  • xml, which is the submitted file (required)
  • replaces, a comma-separated list of Internet-Draft names replaced by this submission (optional)

When an Internet-Draft is submitted, basic checks are performed immediately and an HTTP response is sent including an appropriate http result code and JSON data describing the outcome.

On success, the JSON data format is

{
  "id": "123",
  "name": "draft-just-submitted",
  "rev": "00",
  "status_url": "https://datatracker.ietf.org/api/submission/123/status"
}

On error, the JSON data format is

{
  "error": "Description of the error"
}

If the basic checks passed and a successful response is sent, the Internet-Draft is queued for further processing. Its status can be monitored by issuing GET requests to the status_url indicated in the JSON response. This URL will respond with JSON data in the format

{
  "id": "123",
  "state": "validating"
}

The state validating indicates that the Internet-Draft is being or waiting to be processed. Any other state indicates that the Internet-Draft completed validation. If the validation failed or if the Internet-Draft was canceled after validation, the state will be cancel.

Human-readable details of the Internet-Draft's status and history can be found at https://datatracker.ietf.org/submit/status/123/ (replacing 123 with the id for the submission).)

Here is an example of submitting an Internet-Draft and polling its status through the API:

$ curl -s -F "user=user.name@example.com" -F "xml=@~/draft-user-example.xml" -F "replaces=draft-user-replaced-draft"  https://datatracker.ietf.org/api/submission | jq
{
  "id": "126375",
  "name": "draft-user-example",
  "rev": "00",
  "status_url": "https://datatracker.ietf.org/api/submission/126375/status"
}

$ curl -s https://datatracker.ietf.org/api/submission/126375/status | jq
{
  "id": "126375",
  "state": "validating"
}

$ curl -s https://datatracker.ietf.org/api/submission/126375/status | jq
{
  "id": "126375",
  "state": "auth"
}