This article covers the GraphStudio API, including supported operations, endpoint structure, URI encoding requirements, and error handling. It also introduces key benefits of using the API for workflow automation, integration, and scaling, along with tools to make API interactions easier.
Overview
- Viewing the REST API Documentation
- Endpoints and Supported Methods
- URI Encoding Requirements
- Error Handling
- Tools for Easier API Interaction
- Enabling CORS for Browser Requests
- Next Steps
1. Viewing the API Documentation
The GraphStudio REST API Documentation is a useful tool for working with GraphStudio APIs.
- Access the document on your GraphStudio server at the following URL:
https://<hostname>/api/docs/index.html`
Where <hostname> is the GraphStudio server DNS name or IP address. When you access the API documentation on your server, a “Try It Out” button is available for each request. Clicking Try It Out opens a request body that you can edit and execute against the server.
2. Endpoints and Supported Methods
Core Artifacts and Objects
The GraphStudio API supports create, read, update, and delete operations on:
- Datasets
- Graphmarts
- Data layers
- Steps
Operations on Additional Artifacts and Objects
- Artifact Access Control Lists – Read and update operations.
- Models – Upload, download, and delete.
- Unstructured Pipelines – Run and cancel operations.
- Migration Packages – Import and export.
- Dynamic Launch Configurations and Static AnzoGraph Instances – Read operations.
HTTP Methods
There is an endpoint for each type of GraphStudio artifact or object (dataset, graphmart, layer, step, etc.). Each endpoint supports a subset or all of the following methods:
- POST or PUT – Create
- GET – Read
- PATCH – Update
- DELETE – Delete
3. URI Encoding Requirements
When including a URI (such as a graphmart, layer, or step URI) in the request URL, it must be URL-encoded.
For example, a layer URI:
http://cambridgesemantics.com/Layer/858c521bc7d84364a5a2112e38dc0b52
Becomes URL-encoded as:
http%3A%2F%2Fcambridgesemantics.com%2FLayer%2F858c521bc7d84364a5a2112e38dc0b52
This encoded value is then used in the request URL, for example:
http://10.100.0.10:8080/api/layers/http%3A%2F%2Fcambridgesemantics.com%2FLayer%2F858c521bc7d84364a5a2112e38dc0b52/status
Note: URIs in the body of a request do not need to be URL-encoded.
4. Error Handling
When errors occur, the API returns:
- Summary message – A brief explanation of the issue.
- Detailed message – Additional context about the error.
Stack traces are not included in API responses. To view full stack traces, check the server logs:
https://docs.cambridgesemantics.com/anzo/v5.4/userdoc/admin-view-logs.htm#view-server
The official API documentation also lists all error codes and their meanings under each specific endpoint: Introduction to GraphStudio APIs for Developers | 1. Viewing the API Documentation
5. Tools for Easier API Interaction
While you can use any HTTP client (such as curl or Python’s requests), the following tools simplify API work:
5.1 Python API Wrapper (anzo-api-wrapper)
A Python library that handles low-level HTTP requests, authentication, and error handling for GraphStudio APIs.
5.2 Jupyter Integration (anzo-jupyter)
A package that integrates GraphStudio APIs directly into Jupyter notebooks for interactive development.
6. Optional: Enabling CORS for Browser Requests
If you're building a frontend app that uses the API, you may need to enable Cross-Origin Resource Sharing (CORS):
- Go to Administration → Servers → Advanced Configuration
- Locate the GraphStudio REST API bundle.
- Set org.openanzo.servlet.allowCrossOriginAccess to true.
- Restart GraphStudio.
For further reference and examples of CORS requests, refer to:
https://docs.cambridgesemantics.com/anzo/v5.4/userdoc/api-cors.htm
7. Next Steps
For further reading on the GraphStudio APIs, refer to these articles on:
- Authentication and Token Management
- Creating Migration Packages Programmatically
These resources will help you build out your automation workflows step-by-step.
References
