Add items to ScienceBase using REST protocols

Using ScienceBase API to add records

ScienceBase supports RESTful web services for interacting with the Catalog. Complete documentation about ScienceBase RESTful protocols is available in the development wiki (

To add items to ScienceBase using RESTful methods, user must be logged in and have write permissions to the ScienceBase location to which items are added. JavaScript Object Notation (JSON) is the most supported data exchange format for interacting with ScienceBase. Use of a REST Client (such as Firefox client: chrome://restclient/content/restclient.html) for sending requests and receiving output, and a JSON Validator (such as: for verifying code is recommended. Writing metadata to ScienceBase using the API requires knowledge of the ScienceBase data model - the construction and availability of information fields. The ScienceBase data model and individual fields are explained at:

Helpful Hints for Using REST Client to Interact with ScienceBase

When requesting content from ScienceBase services using GET method, use the Accept header. POST and PUT methods involve both sending and receiving data so both Accept and Content-Type headers should be used to specify data format.

  • Accept: application/json

  • Content-Type: application/json

  • Basic Authorization (log in credentials)

User may log in to ScienceBase using Log in link located in top right corner at Using the same internet browser, user may use REST Client to interact with ScienceBase. The credentials specified in ScienceBase should be recognized without need for user to specify log in credentials in REST Client. However, if user receives authorization errors, passing credentials with REST calls may be required.

- For hints of creating item using JSON format, view JSON examples by visiting a ScienceBase item and selecting JSON link (bottom left corner of summary page) to view alternative representation of the item in JSON format. For example: Every item in ScienceBase may be represented in JSON, ATOM, and ISO XML format.

Use POST operation to create new ScienceBase items

Example - Create simple item

Title and parentId are the minimum requirements for creating new items in ScienceBase, example:

{"parentId":"4f28888de4b050c1ade5f38e","title":"Test Item Title"}

This REST call will create a ScienceBase record related to the record with id of 4f28888de4b050c1ade5f38e. The new item is titled Test Item Title. The Provenance field will automatically display user id of author who created the item and time stamp of the operation.

Example - Create a new project item

    "parentId": "4f513049e4b0edc8611e6f45",
    "title": "Test Project",
    "body": "This project focuses on riparian ecosystems.",
    "contacts": [
            "name": "U.S. Geological Survey",
            "type": "Data Owner",
            "contactType": "organization"
    "browseCategories": [
    "tags": [
            "name": "habitat conservation project"
            "name": "riparian"
    "facets": [
            "projectStatus": "Active",
            "projectType": "Habitat",
            "objectives": [],
            "className": "gov.sciencebase.catalog.item.facet.ProjectFacet"

This REST call will create a new project record associated with item having id: 4f513049e4b0edc8611e6f45. The item is titled Test Project, with a one sentence description. The project extension (also known as facet) is applied to the item, which allows specification of additional information about the project (project status and type).

Site Team