Create a Private Submission

API Endpoint: submission_create

Creates a new private submission.

Important

An API Key is required for ALL private workspace activities

The API Key name component can be added to your header using any of the following ways, “X-CKAN-API-Key”, “EDX-API-Key”, or “Authorization”.

Parameter Definitions

Parameter Name	Description	Required Fields
`type`	`type` must match one of four EDX approved submission types: dataset, tool, publication, presentation	Required
`title`	Title of the Submission (Human readable - spaces and capitalization are allowed)	Required
`name`	URL structured name that must be lowercase and alphanumeric - underscores and dashes are allowed	Required
`description`	Description of the Submission	Required
`citation`	Citation for the Submission	Required
`keywords`	Keywords describing submission. It must be a comma separated string if multiple keywords are listed	Required
`netl_product`	Determines if submission is a product of NETL funded research	Required
`poc_email`	NETL Point of Contact email address	Situational Required
`point_of_contact`	First and Last name of NETL Point of Contact	Situational Required
`program_or_project`	NETL Program or Project the Submission is associated with	Situational Required
`project_number`	NETL project/contract number associated with the NETL funded project	Situational Required
`aiml_product`	Determines if submission is an Artificial Intelligence Machine Learning (AIML) product	Required
`aiml_submission_types`	Submission type associated with the AIML product.	Situational Required
`geospatial_product`	Determines if submission is a Geospatial product	Required
`fgdc_compliant`	Determines if Geospatial product is FGDC Compliant	Situational Required
`publication_date`	Date the Submission will be Published. Format yyyy-mm-dd	Optional
`restriction_date`	Date the submission will be released to the public after approval. Format yyyy-mm-dd	Optional
`maintainer`	First and Last name of the Maintainer	Optional
`maintainer_email`	Email address of the Maintainer	Optional
`workspace_id`	The name or ID of workspace that you wish to add a Submission to if it is intended for Private use	Optional

Author Parameter Definitions

`username`	field used for entering username for a registered EDX user. See Situational Use Cases and `username` in Author Field for more details	Required
`fullname`	field used for entering the full name for a non-registered EDX user. See Situational Use Cases and `fullname` in Author Field for more details	Required
`type`	field to define the author type for the submission. See Situational Use Cases and `type` in Author Field for more details	Required

Situational Use Cases

Note

“SITUATIONAL” REQUIRED PARAMETERS ARE ONLY REQUIRED IN SPECIFIC USE CASES.

If netl_product is ‘yes’ the following parameters are required
- poc_email is required when “netl_product” parameter field is ‘yes’
- point_of_contact is required when “netl_product” parameter field is ‘yes’
- program_or_project is required when “netl_product” parameter field is ‘yes’
- project_number is required when “netl_product” parameter field is ‘yes’
If aiml_product product is ‘yes’ the following parameters are required
- aiml_submission_types is required when “aiml_product” parameter field is ‘yes’
If geospatial_product product is ‘yes’ the following parameters are required
- fgdc_compliant is required when “geospatial_product” parameter field is ‘yes’
If the author is a registered EDX user, the first field in the Authors dictionary will be username
If the author is NOT** a registered EDX user, the first field in the Authors dictionary will be fullname

EDX Approved Submission types

Note

Submission types must match one of four EDX approved submission types.

dataset
tool
publication
presentation

AIML types

Note

The Artificial Intelligence / Machine Learning (AIML) data field must match at least one of five AIML types.

compiledModel
trainingData
gitLinkModel
aiMethodDoc
aiResource

Workspace ID Field

workspace_id field is required to create a private submission

Attention

Not including a workspace_id will create a public submission

Tip

A workspace’s id is the text that appears in the address bar, it is NOT the plain text title found in the body of the website.

For Example (workspace id),

Use sample-edx-workspace

Do NOT use Sample EDX Workspace

Important

When defining workspace ID, ONLY select the end path of the URL

Authors Field

Within the Authors dictionary, there are required fields to add authors to a submission
- username : ‘edx-author-username’
- fullname : ‘non-edx-author-full-name’
- type : ‘author-type’

Note

type parameter in the Authors dictionary only accepts specific types for the field

‘Author’
‘Contact’
‘Contributor’

Note

The order in which the authors are input into the Authors dictionary, will be the order that is present on the web submission-test-2025-01-28-14-13-21

Example 1: Create a New Basic Private Submission with a Registered EDX User as Author

Attention

Add the "User-Agent": parameter within the headers of the API request
Set "User-Agent": to the value "EDX-USER"

Important

In Authors dictionary, the first parameter must be set to username for this example
A Valid EDX username must be entered as the value for the username parameter

python
Successful Output
Failed Output

import requests

headers = {
    "EDX-API-Key": 'YOUR_API_KEY_HERE',
    "User-Agent": 'EDX-USER',
    'Content-Type': 'application/json',
    'Accept':'application/json'
}

data = {
    'type': 'SUBMISSION_TYPE_HERE',
    'title': 'TITLE_OF_SUBMISSION',
    'name': 'NAME_HERE',
    'description': 'DESCRIPTION_HERE',
    'citation': 'LIST_CITATIONS_HERE',
    'keywords': 'KEYWORDS_HERE',
    'netl_product': 'YES-OR-NO',
    'aiml_product': 'YES-OR-NO',
    'geospatial_product': 'YES-OR-NO',
    'workspace_id': 'WORKSPACE-ID-HERE'
    #AUTHOR_TYPES: author, contact, contributor
    'authors': [
      {
        'username': 'EDX-AUTHOR-USERNAME',
        'type': 'AUTHOR-TYPE'
      },
    ],
}

url = 'https://edx.netl.doe.gov/api/3/action/submission_create'
r = requests.post(
    url, # URL to API endpoint
    headers=headers, # Headers dictionary
    json=data, # Dictionary of data params

)
r_json = r.json()
print (r.json())

{'help': '/api/3/action/help_show?name=submission_create', 'success': True, 'result': {'id': 'e7097c64-980a-4f23-9271-73b411dd3978', 'authors': [{'id': 'd3083789-6e6c-4e0d-b55d-cf47d6751be5',
 'name': 'atticus-finch', 'fullname': 'Atticus Finch', 'type': 'author', 'position': 0}], 'creator_user_id': 'd3083789-6e6c-4e0d-b55d-cf47d6751be5',
  'description': 'Repository..', 'keywords': 'Test, Testing, Author-Test', 'name': 'submission-test-2025-01-28-14-13-21', 'maintainer': None,
  'maintainer_email': None, 'metadata_created': '2025-01-28 15:13', 'metadata_modified': '2025-01-28 15:13', 'num_resources': 0, 'workspace_id': None,
  'package_reviewed': False, 'private': False, 'state': 'draft', 'title': 'Testing Date -2025-01-28-14-13-21', 'type': 'dataset', 'non_edx_authors': [],
  'publication_date': None, 'restriction_date': None, 'netl_product': 'no', 'poc_email': [], 'point_of_contact': None, 'program_or_project': None, 'project_number': None,
  'aiml_product': 'no', 'aiml_submission_types': None, 'geospatial': 'no', 'fgdc_compliant': None}}

{'help': '/api/3/action/help_show?name=submission_create', 'error': {'authors': ['Author type "kljh" is not valid. Allowed author types are: author, contact, or contributor.'],
'__type': 'Validation Error'}, 'success': False}

Example 2: Create a New Basic Private Submission with Author who isn’t a Registered EDX User

Attention

Add the "User-Agent": parameter within the headers of the API request
Set "User-Agent": to the value "EDX-USER"

Important

In Authors dictionary, the first parameter must be set to fullname for this example
A Valid first and last name must be entered as the value for the fullname parameter
- Example: 'fullname': 'First Last'

python
Successful Output
Failed Output

import requests

headers = {
    "EDX-API-Key": 'YOUR_API_KEY_HERE',
    "User-Agent": 'EDX-USER',
    'Content-Type': 'application/json',
    'Accept':'application/json'
}

data = {
    'type': 'SUBMISSION_TYPE_HERE',
    'title': 'TITLE_OF_SUBMISSION',
    'name': 'NAME_HERE',
    'description': 'DESCRIPTION_HERE',
    'citation': 'LIST_CITATIONS_HERE',
    'keywords': 'KEYWORDS_HERE',
    'netl_product': 'YES-OR-NO',
    'aiml_product': 'YES-OR-NO',
    'geospatial_product': 'YES-OR-NO',
    #AUTHOR_TYPES: author, contact, contributor
    'authors': [
      {
        'fullname': 'NON-EDX-AUTHOR-FULL-NAME',
        'type': 'AUTHOR-TYPE'
      },
    ],
}

url = 'https://edx.netl.doe.gov/api/3/action/submission_create'
r = requests.post(
    url, # URL to API endpoint
    headers=headers, # Headers dictionary
    json=data, # Dictionary of data params

)
r_json = r.json()
print (r.json())

{'help': '/api/3/action/help_show?name=submission_create', 'success': True, 'result': {'id': '0c54fc39-34ee-458e-9a2b-350d55dd71cb', 'authors': [],
'creator_user_id': 'd3083789-6e6c-4e0d-b55d-cf47d6751be5', 'description': 'Test-Description', 'keywords': 'Test, Testing, Author-Test',
'name': 'submission-test-2025-01-28-14-27-44', 'maintainer': None, 'maintainer_email': None, 'metadata_created': '2025-01-28 15:27',
'metadata_modified': '2025-01-28 15:27', 'num_resources': 0, 'workspace_id': None, 'package_reviewed': False, 'private': False, 'state': 'draft',
'title': 'Testing Date -2025-01-28-14-27-44', 'type': 'dataset', 'non_edx_authors': [{'fullname': 'Scout Finch', 'type': 'contributor', 'position': 0}],
'publication_date': None, 'restriction_date': None, 'netl_product': 'no', 'poc_email': [{'fullname': 'Scout Finch', 'type': 'contributor', 'position': 0}],
'point_of_contact': None, 'program_or_project': None, 'project_number': None, 'aiml_product': 'no', 'aiml_submission_types': None, 'geospatial': 'no',
'fgdc_compliant': None}}

{'help': '/api/3/action/help_show?name=submission_create', 'error': {'authors': ['Author type "kljh" is not valid. Allowed author types are: author, contact, or contributor.'],
'__type': 'Validation Error'}, 'success': False}

Example 3: Create a New Basic Private Submission with Multiple Authors (EDX user and non-EDX user)

Attention

Add the "User-Agent": parameter within the headers of the API request
Set "User-Agent": to the value "EDX-USER"

Important

In Authors dictionary, the first parameter must be set to username for Registered EDX users
A Valid EDX username must be entered as the value for the username parameter

Important

In Authors dictionary, the first parameter must be set to fullname for non-EDX users
A Valid first and last name must be entered as the value for the fullname parameter
- Example: 'fullname': 'First Last'

python
Successful Output
Failed Output

import requests

headers = {
    "EDX-API-Key": 'YOUR_API_KEY_HERE',
    "User-Agent": 'EDX-USER',
    'Content-Type': 'application/json',
    'Accept':'application/json'
}

data = {
    'type': 'SUBMISSION_TYPE_HERE',
    'title': 'TITLE_OF_SUBMISSION',
    'name': 'NAME_HERE',
    'description': 'DESCRIPTION_HERE',
    'citation': 'LIST_CITATIONS_HERE',
    'keywords': 'KEYWORDS_HERE',
    'netl_product': 'YES-OR-NO',
    'aiml_product': 'YES-OR-NO',
    'geospatial_product': 'YES-OR-NO',
    #AUTHOR_TYPES: author, contact, contributor
    'authors': [
      {
        'username': 'EDX-AUTHOR-USERNAME',
        'type': 'AUTHOR-TYPE'
      },
      {
        'fullname': 'NON-EDX-AUTHOR-FULL-NAME',
        'type': 'AUTHOR-TYPE'
      },
    ],
}

url = 'https://edx.netl.doe.gov/api/3/action/submission_create'
r = requests.post(
    url, # URL to API endpoint
    headers=headers, # Headers dictionary
    json=data, # Dictionary of data params

)
r_json = r.json()
print (r.json())

{'help': '/api/3/action/help_show?name=submission_create', 'success': True, 'result': {'id': 'fd095916-7d7b-4e9d-83be-51f7d9e9dafb',
'authors': [{'id': 'd3083789-6e6c-4e0d-b55d-cf47d6751be5', 'name': 'edx-user', 'fullname': 'EDX User', 'type': 'author', 'position': 0}],
'creator_user_id': 'd3083789-6e6c-4e0d-b55d-cf47d6751be5', 'description': 'Repository..', 'keywords': 'Test, Testing, Author-Test', 'name':
'submission-test-2025-01-28-14-36-09', 'maintainer': None, 'maintainer_email': None, 'metadata_created': '2025-01-28 15:36', 'metadata_modified':
'2025-01-28 15:36', 'num_resources': 0, 'workspace_id': None, 'package_reviewed': False, 'private': False, 'state': 'draft', 'title':
'Testing Date -2025-01-28-14-36-09', 'type': 'dataset', 'non_edx_authors': [{'fullname': 'Jem Finch', 'type': 'contact', 'position': 1}],
'publication_date': None, 'restriction_date': None, 'netl_product': 'no', 'poc_email': [{'fullname': 'Jem Finch', 'type': 'contact', 'position': 1}],
'point_of_contact': None, 'program_or_project': None, 'project_number': None, 'aiml_product': 'no', 'aiml_submission_types': None, 'geospatial': 'no',
'fgdc_compliant': None}}

{'help': '/api/3/action/help_show?name=submission_create', 'error': {'authors': ['No user found with the username Incorrect-Username. If your author does not have an EDX account, provide "fullname" in your request data.'], '__type': 'Validation Error'},
'success': False}

Example 4 : Create a New Private Submission with Additional NETL and Geospatial Fields

Attention

Add the "User-Agent": parameter within the headers of the API request
Set "User-Agent": to the value "EDX-USER"

Successful Input
Successful Output
Failed Input
Failed Output

  import requests

  headers = {
      "EDX-API-Key": 'YOUR_API_KEY_HERE',
      "User-Agent": 'EDX-USER',
      'Content-Type': 'application/json',
      'Accept':'application/json'
  }

  data = {
      'type': 'dataset', # type must match one of four EDX approved submission types: dataset, tool, publication, presentation. Required
      'title': 'Example Submission', #Required
      'name': 'example-submission', #Must have at least 2 alphanumeric characters. Must be all lowercase and supports underscores and dashes.Required
      'description': 'This is an example.', #Required
      'citation': 'John Smith, Example Submission, 5/24/2024, https://edx.netl.doe.gov/dataset/example-submission', #Required
      'keywords': 'example, example2', #Required. Can be a comma separated string
      'netl_product': 'yes', # If not y, yes, or True, 'True' == no. Required
      'poc_email': 'scout.finch@netl.doe.gov', #required if netl_product is yes. Ignored if netl_product is no or missing. must have @netl.doe.gov or @contr.netl.doe.gov in email
      'point_of_contact': 'Scout Finch', #required if netl_product is yes. Ignored if netl_product is no or missing.
      'program_or_project': 'Geothermal 4D', #required if netl_product is yes. Ignored if netl_product is no or missing.
      'project_number': '1234567', #required if netl_product is yes. Ignored if netl_product is no or missing.
      'aiml_product': 'yes', #If not y, yes, or True, 'True' == no . Required
      'aiml_submission_types': [ "compiledModel", "gitLinkModel", "aiResource" ], #required if aiml_product is yes. Must be an array. Items in list must match one of 5 types.Ignored if aiml_product is no or missing.
      'geospatial_product': 'yes', # If not y, yes, or True, 'True' == no . Required
      'fgdc_compliant': 'no' , # If not y, yes, or True, 'True' == no . Required if geospatial_product is yes. Ignored if geospatial_product is missing.
      'publication_date': '2024-05-24', # format yyyy-mm-dd
      'restriction_date': '2025-01-31', # format yyyy-mm-dd
      'maintainer': 'Jack Horner',
      'maintainer_email': 'jack.horner@netl.doe.gov', # Must be valid email format.
      #AUTHOR_TYPES: author, contact, contributor
      'authors': [
        {
          'username': 'EDX-AUTHOR-USERNAME',
          'type': 'AUTHOR-TYPE'
        },
        {
          'fullname': 'NON-EDX-AUTHOR-FULL-NAME',
          'type': 'AUTHOR-TYPE'
        },
      ],
  }

  url = 'https://edx.netl.doe.gov/api/3/action/submission_create'
  r = requests.post(
      url, # URL to API endpoint
      headers=headers, # Headers dictionary
      json=data, # Dictionary of data params

  )
  r_json = r.json()
  print (r.json())

{'help': '/api/3/action/help_show?name=submission_create', 'success': True, 'result': {'id': 'c1abbb28-cf51-48bf-98e5-a7f07b5973e3',
'authors': [{'id': 'd3083789-6e6c-4e0d-b55d-cf47d6751be5', 'name': 'edx-user', 'fullname': 'EDX USER', 'type': 'author', 'position': 0}],
'creator_user_id': 'd3083789-6e6c-4e0d-b55d-cf47d6751be5', 'description': 'This is an example.', 'keywords': 'example, example2', 'name':
'test-multi-netl-author', 'maintainer': 'Jack Horner', 'maintainer_email': 'jack.horner@netl.doe.gov', 'metadata_created': '2025-01-28 15:46',
'metadata_modified': '2025-01-28 15:46', 'num_resources': 0, 'workspace_id': None, 'package_reviewed': False, 'private': False, 'state': 'draft',
'title': 'Example Submission', 'type': 'dataset', 'non_edx_authors': [{'fullname': 'Scout Finch', 'type': 'contact', 'position': 1}],
'publication_date': '2024-05-24', 'restriction_date': '2025-01-31', 'netl_product': 'yes', 'poc_email': [{'fullname': 'Scout Finch', 'type':
'contact', 'position': 1}], 'point_of_contact': 'Scout Finch', 'program_or_project': 'Geothermal 4D', 'project_number': '1234567', 'aiml_product':
'yes', 'aiml_submission_types': ['compiledModel', 'gitLinkModel', 'aiResource'], 'geospatial': 'yes', 'fgdc_compliant': None}}

import requests

headers = {
    "EDX-API-Key": 'YOUR_API_KEY_HERE',
    "User-Agent": 'EDX-USER',
    'Content-Type': 'application/json',
    'Accept':'application/json'
}

data = {
    'type': 'dataset', # type must match one of four EDX approved submission types: dataset, tool, publication, presentation. Required
    'title': 'Example Submission', #Required
    'name': 'example-submission', #Must have at least 2 alphanumeric characters. Must be all lowercase and supports underscores and dashes.Required
    'description': 'This is an example.', #Required
    'citation': 'John Smith, Example Submission, 5/24/2024, https://edx.netl.doe.gov/dataset/example-submission', #Required
    'keywords': 'example, example2', #Required. Can be a comma separated string
    'netl_product': 'yes', # If not y, yes, or True, 'True' == no. Required
    'poc_email': 'scout.finch@example.com', #required if netl_product is yes. Ignored if netl_product is no or missing. must have @netl.doe.gov or @contr.netl.doe.gov in email
    'point_of_contact': 'Scout Finch', #required if netl_product is yes. Ignored if netl_product is no or missing.
    'program_or_project': 'Geothermal 4D', #required if netl_product is yes. Ignored if netl_product is no or missing.
    'project_number': '1234567', #required if netl_product is yes. Ignored if netl_product is no or missing.
    'aiml_product': 'yes', #If not y, yes, or True, 'True' == no . Required
    'aiml_submission_types': [ "compiledModel", "gitLinkModel", "aiResource" ], #required if aiml_product is yes. Must be an array. Items in list must match one of 5 types.Ignored if aiml_product is no or missing.
    'geospatial_product': 'yes', # If not y, yes, or True, 'True' == no . Required
    'fgdc_compliant': 'no' , # If not y, yes, or True, 'True' == no . Required if geospatial_product is yes. Ignored if geospatial_product is missing.
    'publication_date': '2024-05-24', # format yyyy-mm-dd
    'restriction_date': '2025-01-31', # format yyyy-mm-dd
    'maintainer': 'Jack Horner',
    'maintainer_email': 'jack.horner@netl.doe.gov', # Must be valid email format.
    #AUTHOR_TYPES: author, contact, contributor
    'authors': [
      {
        'username': 'EDX-AUTHOR-USERNAME',
        'type': 'AUTHOR-TYPE'
      },
      {
        'fullname': 'NON-EDX-AUTHOR-FULL-NAME',
        'type': 'AUTHOR-TYPE'
      },
    ],
}

url = 'https://edx.netl.doe.gov/api/3/action/submission_create'
r = requests.post(
    url, # URL to API endpoint
    headers=headers, # Headers dictionary
    json=data, # Dictionary of data params

)
r_json = r.json()
print (r.json())

{'help': '/api/3/action/help_show?name=submission_create', 'error': {'netl_product': ['poc_email: Your poc_email must have @netl.doe.gov or @contr.netl.doe.gov email address.'],
'__type': 'Validation Error'}, 'success': False}