Getting Started with the National Archives Catalog API
How to run your first API call:
Step 1: Open the Command-Line Interface (CLI)
- Windows: Press Windows + R, type
cmd, and press Enter to open the Command Prompt. - Mac: Press Command + Space, type
Terminal, and press Enter. - Linux: Open the Terminal from your system's applications menu or press Ctrl + Alt + T.
Step 2: Install curl (if it's not already installed)
- Windows: Recent versions of Windows include curl by default. To check, type
curl --versionand press Enter. - Mac and Linux: curl is typically pre-installed. To check, type
curl --versionin the terminal and press Enter.
Step 3: Get your API Key
- Make sure you have your API key that was provided by our Catalog engineers. You will replace
YOUR_API_KEYin the command with the API key issued by our Catalog engineers.
Step 4: Run the curl Command
- Once you have curl installed and your API key ready, you can run the following command in the terminal.
curl --location --request GET "https://catalog.archives.gov/api/v2/records/search?q=constitution" --header "Content-Type: application/json" --header "x-api-key: YOUR_API_KEY"Step 5: View the Response
- After running the command, you should see a response from the API printed in the terminal. It will be a JSON-formatted output that includes the search results.
Step 6: Saving the Output (Optional)
- If you want to save the output to a file instead of viewing it in the terminal, you can modify the command like this:
curl --location --request GET "https://catalog.archives.gov/api/v2/records/search?q=constitution" --header "Content-Type: application/json" --header "x-api-key: YOUR_API_KEY" -o output.json- The
output.jsoncommand will save the results to a JSON file in the current directory.
Note: You may use various methods including API platforms, Python, PowerShell, etc., to formulate and execute your queries.
Sample API Query: Read-Only
Use Case:
- I want to retrieve a list of NAIDs for sound recordings related to "Project Blue Book" that are available online.
Query Parameters:
- typeOfMaterials - photographs and other graphic materials, moving images, textual records, maps and charts, sound recordings, artifacts, etc.
- q - a keyword search string which accepts boolean operators (AND, OR, NOT), wildcards (*), and exact phrases ("").
- availableOnline - records at the Item and File Unit levels which contain digital objects and can be viewed online.
To view a full list of query parameters, please see our Swagger documentation.
API Program GET Request Query Structure:
https://catalog.archives.gov/api/v2/records/search?availableOnline=true&q=project blue book&typeOfMaterials=Sound Recordings
Curl Command Line Interface Structure::
curl --location --request GET "https://catalog.archives.gov/api/v2/records/search?availableOnline=true&q=project+blue+book&typeOfMaterials=Sound+Recordings" --header "Content-Type: application/json" --header "x-api-key: YOUR_API_KEY"JSON Response:
{
"body": {
"hits": {
"total": {
"value": 1,
"relation": "eq"
},
"max_score": null,
"hits": [
{
"_index": "nac-records2",
"_id": "417180915",
"_score": 83.65058,
"_source": {
"metadata": {
"fileName": "NAC_2024-09-07_DESC_0005.xml",
"controlGroup": {
"indexName": "records",
"type": "collection",
"naId": 597542
},
"ingestTime": "2024-09-08 11:01:41.466499",
"uuid": "8812180a-41f2-4ea3-aa7d-611b52552680"
},
"record": {
"levelOfDescription": "item",
"recordType": "description",
"useRestriction": {
"status": "Unrestricted"
},
"audiovisual": "True",
"title": "Tape 677, Conversation 010 (677-010)",
"physicalOccurrences": [
{
"totalFootage": 0,
"referenceUnits": [
{
"city": "Yorba Linda",
"phone": "714-983-9120",
"address1": "18001 Yorba Linda Boulevard",
"postalCode": "92886",
"name": "Richard Nixon Library",
"state": "CA",
"fax": "714-983-9111",
"email": "nixonreference@nara.gov",
"mailCode": "LP-RN"
}
],
"mediaOccurrences": [
{
"generalMediaTypes": [
"Magnetic Media"
],
"specificMediaType": "Networked Storage"
}
],
"copyStatus": "Reproduction-Reference"
}
],
"accessRestriction": {
"status": "Unrestricted"
},
"dataControlGroup": {
"groupName": "Richard Nixon Library",
"groupId": "PL-RN",
"groupCd": "PL-RN"
},
"generalRecordsTypes": [
"Sound Recordings"
],
"localIdentifier": "wht-677-010",
"productionDates": [
{
"month": 3,
"year": 1972,
"day": 6,
"logicalDate": "1972-03-06"
}
],
"digitalObjects": [
{
"objectFilename": "37-wht-conversation-677-010-pa.mp3",
"objectUrl": "https://s3.amazonaws.com/NARAprodstorage/lz/presidential-libraries/nixon/rn-wht/17409633/6852408/37-wht-conversation-677-010-pa.mp3",
"objectFileSize": 110456992,
"objectId": "417180916",
"objectType": "Sound File (MP3)"
}
],
"ancestors": [
{
"collectionIdentifier": "RN-WHT",
"inclusiveStartDate": {
"month": 2,
"year": 1971,
"day": 16,
"logicalDate": "1971-02-16"
},
"distance": 3,
"levelOfDescription": "collection",
"inclusiveEndDate": {
"month": 7,
"year": 1973,
"day": 18,
"logicalDate": "1973-07-18"
},
"title": "White House Tapes: Sound Recordings of Meetings and Telephone Conversations of the Nixon Administration",
"naId": 597542
},
{
"inclusiveStartDate": {
"month": 2,
"year": 1971,
"day": 16,
"logicalDate": "1971-02-16"
},
"distance": 2,
"levelOfDescription": "series",
"creators": [
{
"creatorType": "Most Recent",
"heading": "President (1969-1974 : Nixon). Office of the President. ( 01/20/1969 - 08/1974)",
"abolishDate": {
"month": 8,
"year": 1974,
"logicalDate": "1974-08-01"
},
"authorityType": "organization",
"establishDate": {
"month": 1,
"year": 1969,
"day": 20,
"logicalDate": "1969-01-20"
},
"naId": 10447055
}
],
"inclusiveEndDate": {
"month": 7,
"year": 1973,
"day": 12,
"logicalDate": "1973-07-12"
},
"title": "Oval Office Sound Recordings",
"naId": 17409633
},
{
"distance": 1,
"levelOfDescription": "fileUnit",
"title": "Oval Office Tape Number 677",
"naId": 6852408
}
],
"scopeAndContentNote": "On March 6, 1972, President Richard M. Nixon, H. R. (\"Bob\") Haldeman, John D. Ehrlichman, and Alexander P. Butterfield met in the Oval Office of the White House from 12:31 pm to 1:28 pm. The Oval Office taping system captured this recording, which is known as Conversation 677-010 of the White House Tapes.\n\nTopics include: The President met with H. R. (\"Bob\") Haldeman, John D. Ehrlichman and Alexander P. Butterfield. The President's schedule Butterfield left at 12:31 pm. Education - Blacks - Ehrlichman's view - Paper presented by an unknown person - Constitutional amendment - Press - Congress - Hugh Scott - The President's forthcoming meeting with the Cabinet Committee on Education - Final paper - Department of Health, Education and Welfare [HEW] - Justice Department - Office of Legal Counsel - Civil Rights Division - White House role Speech on busing - Raymond K. Price, Jr. - Amendments - Ehrlichman's view - Haldeman's view - First draft - Price -\"Soft\" moratorium - Editing - Patrick J. Buchanan - Constitutional amendment - Blacks - The President's forthcoming meeting with George W. Romney - Elliot L. Richardson - Projecting press headlines - Moratorium - Constitutional amendment - Price's draft [Previous PRMPA Personal Returnable (G) withdrawal reviewed under deed of gift 08/26/2022. Segment cleared for release.] [Personal Returnable] [677-010- W001] [Duration: 2m 1s] 1972 campaign - Edmund S. Muskie - Raymond K. Price, Jr. - George S. McGovern - Florida [?] - Henry M. (\"Scoop\") Jackson - George C. Wallace - Hubert H. Humphrey - The President's chances as a candidate - Drugs - Foreign affairs - Economy - The President's August 15, 1971 speech - Cities Patrick J. Buchanan - The President's view - Buchanan's efforts - Supreme Court problems - Day care centers - Cambodia - Anti- Ballistic missiles [ABM] - Staff conservatives - Leonard Garment - Public relations efforts - Possible resignation - Ehrlichmans's view - Trip to the People's Republic of China [PRC] - Talk with Haldeman - Buchanan's support for the President's position - As staff member - As private citizen - Role in campaign - Role in White House - Buchanan's view of the Shanghai Communiqué - Henry A. Kissinger - Alexander M. Haig, Jr. - William P. Rogers - The President's re- Election - Shanghai Communiqué - Haldeman's view - Journalism - Role as policy maker - Shelly A. (Scarney) Buchanan -1972 election - The President's trip to the PRC - Buchanan's criticism of the wording of the Communiqué - Japan - PRC compared to China - Kissinger - Rogers - US treaty commitments - Japan - Taiwan - PRC treaty commitments - North Vietnam - Rogers - Buchanan in foreign policy field - Taiwan, Republic of China - Soviet Union - Talk with Haig - Soviet Union - The President's view - Triangular diplomacy - Kissinger - Taiwan - Japan - India - Philippines - Thailand - Cambodia - Work with conservatives - House Resolution [HR] 1 - Day care - Liberals - John N. Ashbrook candidacy - News summary [Previous PRMPA Personal Returnable (G) withdrawal reviewed under deed of gift 08/26/2022. Segment cleared for release.] [Personal Returnable] [677-010- W003] [Duration: 2m 58s] Patrick J. Buchanan - Work with conservatives - Day care - John N. Ashbrook candidacy - Previous meeting with William F. Buckley - People's Republic of China [PRC] - California nomination - New Hampshire primary - William F. Buckley's advice to John N. Ashbrook - Florida primary - California - Communique - Henry M. (\"Scoop\") Jackson - California - Percentages -1952 California primary - Earl Warren - William F. Knowland Press conference - Ehrlichman - PRC - Busing - Camp David - The President's forthcoming meeting with the Cabinet Committee on Education International Telephone and Telegraph [ITT] case - John N. Mitchell's statement - President's statement - Peter M. Flanigan - Richard G. Kleindienst - Talk with Ehrlichman - Dita D. Beard's doctor - Jack N. Anderson - Beard - Knowledge of memorandum contents - Conversation with Mitchell - Meeting at Louie B. Nunn's house - Beard's social life - Doctor's testimony - Mitchell's statement - Possible public statement - President - Investigation - The President's relationship with Mitchell - Kleindienst's nomination - Settlement procedure - Flanigan and Kleindienst - Harold S. Geneen - Canteen Corporation - Geneen meeting with Ehrlichman - Justice Department negotiations - Talk with Mitchell - Mitchell's talk with Richard W. McLaren - Mitchell's self- Disqualification - Kleindienst role - Flanigan role - Hiring of economic consultant - Job description - Determination of consultant - San Diego contribution - Republican party - Financial status - Anti- Trust - Ehrlichman's memorandum to Mitchell - Prosecution's actions - McLaren's actions - Anderson - View of situation - Quid pro quo Elmer H. Bobst - Cancer information - Appointment as special consultant to the President's Cancer Panel -[Forename unkown] Baker White House staff - Buchanan - Political extremists ITT case - Knowledge of situation - Charles W. Colson - Flanigan - William L. Safire - Contributions - Richard A. Moore - Justice Department - Kleindienst - Anderson papers - Book Book published - PRC trip - Ehrlichman's view of book - Timing of publication Housing policy - Edward L. Morgan - The President's forthcoming meeting with George W. Romney White House news summaries - Emphasis on negative stories - The President's view - Kissinger Ashbrook - California William F. Buckley, Jr. - US Information Agency [USIA] advisory committee - PRC trip James J. Kilpatrick, Jr. - William S. White - Lunch with Ehrlichman Busing - Blue ribbon committee - Blacks - Liberals - Scott and Michael J. Mansfield Construction project - Memorandum Haldeman's recent talk with Buchanan Haldeman and Ehrlichman left at 1:28 pm.\n\nParticipants: Nixon, Richard M. (President); Haldeman, H. R. (\"Bob\"); Ehrlichman, John D.; Butterfield, Alexander P.",
"naId": 417180915
}
},
"sort": [
83.65058,
"417180915"
]
}
]
},
"aggregations": {
"typeOfMaterials": {
"doc_count_error_upper_bound": 0,
"sum_other_doc_count": 0,
"buckets": [
{
"key": "Sound Recordings",
"doc_count": 1
}
]
},
"collectionIdentifier": {
"doc_count": 3,
"filter_collections": {
"doc_count": 1,
"collections": {
"doc_count_error_upper_bound": 0,
"sum_other_doc_count": 0,
"buckets": [
{
"key": "RN-WHT: White House Tapes: Sound Recordings of Meetings and Telephone Conversations of the Nixon Administration",
"doc_count": 1
}
]
}
}
},
"referenceUnits": {
"doc_count_error_upper_bound": 0,
"sum_other_doc_count": 0,
"buckets": [
{
"key": "Richard Nixon Library",
"doc_count": 1
}
]
},
"levelOfDescription": {
"doc_count_error_upper_bound": 0,
"sum_other_doc_count": 0,
"buckets": [
{
"key": "item",
"doc_count": 1
}
]
},
"recordGroupNumber": {
"doc_count": 3,
"filter_recordGroups": {
"doc_count": 0,
"recordGroups": {
"doc_count_error_upper_bound": 0,
"sum_other_doc_count": 0,
"buckets": []
}
}
},
"availableOnline": {
"doc_count": 1
},
"dataSource": {
"doc_count_error_upper_bound": 0,
"sum_other_doc_count": 0,
"buckets": [
{
"key": "description",
"doc_count": 1
}
]
},
"objectType": {
"doc_count_error_upper_bound": 0,
"sum_other_doc_count": 0,
"buckets": [
{
"key": "Sound File (MP3)",
"doc_count": 1
}
]
},
"localIdentifierCount": {
"doc_count": 1
}
}
},
"statusCode": 200,
"headers": {
"date": "Mon, 12 May 2025 20:00:35 GMT",
"content-type": "application/json; charset=UTF-8",
"content-length": "9825",
"connection": "keep-alive",
"access-control-allow-origin": "*"
}
}
Sample API Query: Write User Contributions
To write to the National Archives Catalog via the API, a Catalog user ID in the format of a Universally Unique Identifier (UUID) is required in the body of the request, in addition to the Catalog API key. Contributions include tags, transcriptions, and comments.
Learn more about our Citizen Archivist missions and ways you can make contributions to the National Archives Catalog by visiting the Citizen Archivist Dashboard.
How to obtain your Universally Unique Identifier (UUID):
Step 1: Log in to your Catalog user profile on catalog.archives.gov to see your latest contributions.
- If you have not yet added a contribution, we recommend selecting a Catalog record with zero to few existing contributions. This will make it easier to locate your unique identifier.
Step 2: Click on your most recently added contribution.
- This will take you to the URL for the Catalog record and include the contributionId. The below example will take you to https://catalog.archives.gov/id/305558927?contributionId=ce2bf243-bc1b-4a14-82ae-1a4ace8b30d2.
Step 3: Run a Catalog API GET request to retrieve your Universally Unique Identifier (UUID).
- Using the example above, the GET request for this record would be:
https://catalog.archives.gov/api/v2/contributions/?targetNaId=305558927
Step 4: Parse the JSON response to find your Universally Unique Identifier (UUID).
- Search for the contributionId noted in the Catalog URL. In the above example this is:
ce015dd2-7646-4f85-b6b1-002ba585d6e0 - Locate the parameter userId within this contribution container. This value is your Universally Unique Identifier (UUID).
{
"id": 23959746,
"contributionId": "ce015dd2-7646-4f85-b6b1-002ba585d6e0",
"contributionType": "tag",
"contribution": "Unidentified Aerial Phenomena",
"status": "active",
"contributionSequence": 1,
"parentContributionId": null,
"targetNaId": 305558927,
"targetObjectId": null,
"targetPageNum": null,
"flagged": 0,
"reviewed": 0,
"madeByAdministrator": 0,
"userId": "b857fab1-68da-4044-878b-0c2eddbd8a2b",
"justificationId": null,
"legacyAnnotationId": null,
"createdAt": "2025-05-15T16:08:45.000Z",
"updatedAt": "2025-05-15T16:08:45.000Z",
"recordType": null,
"aiMachineGenerated": 0,
"userName": "catalogapidemo",
"fullName": null,
"naraStaff": 0,
"replies": [],
"parentComment": []
},
Use Case:
- My read-only query returned one result for sound recordings related to "Project Blue Book" that are available online: Tape 677, Conversation 010 (677-010) (NAID 417180915). I want to add a tag to this record that identifies it as related to Unidentified Aerial Phenomena so other users can find it more easily.
Query Parameters:
- A POST request does not use query parameters. Instead, it requires a JSON-formatted body with the necessary data fields.
JSON Request Body:
{
"tag": "Unidentified Aerial Phenomena",
"targetNaId": 417180915,
"userId": "YOUR_UUID",
"status": "active"
}API Program POST Request Query Structure:
https://catalog.archives.gov/api/v2/tags/
Curl Command Line Interface Structure:
curl -X POST "https://catalog.archives.gov/api/v2/tags/" -H "Content-Type: application/json" -H "x-api-key: YOUR_API_KEY" -d "{\"tag\":\"Unidentified Aerial Phenomena\",\"targetNaId\":417180915,\"userId\":\"YOUR_UUID\",\"status\":\"active\"}"JSON Response:
{
"result": "tag successfully added",
"contribution": "Unidentified Aerial Phenomena",
"contributionId": "e1af2882-4611-4123-9c53-147cf6674d24",
"targetNaId": 417180915,
"userId": "b857fab1-68da-4044-878b-0c2eddbd8a2b",
"status": "active"
}To learn more about query parameters or use cases for the Catalog API, please visit the Catalog API GitHub or see our Swagger documentation.