API Overview
Last updated
The Viio GraphQL API is the primary interface for programmatic access to your SaaS management data.
Endpoint
All GraphQL requests are sent to a single endpoint:
POST https://api.viio.io/graphql
Why GraphQL?
GraphQL lets you request exactly the data you need in a single request. Instead of calling multiple REST endpoints, you describe the shape of the data you want and the API returns it.
query {
licenses(first: 5) {
nodes {
state
annualPrice {
currency
amount
}
plan {
name
integration {
name
}
}
}
}
}
This single query returns the first 5 licenses with their pricing, plan, and the plan's integration — something that would require multiple requests with a traditional REST API.
Making Your First Request
Make sure you have an API key, then send a query:
curl -X POST https://api.viio.io/graphql \
-H "Content-Type: application/json" \
-H "Authorization: YOUR_API_KEY" \
-d '{
"query": "{ applications(first: 3) { nodes { id state application { name } } }"
}'
Response
{
"data": {
"applications": {
"nodes": [
{
"id": "6650a3f1e4b0...",
"state": "SANCTIONED",
"application": { "name": "Slack" }
},
{
"id": "6650a3f1e4b1...",
"state": "SANCTIONED",
"application": { "name": "GitHub" }
},
{
"id": "6650a3f1e4b2...",
"state": "DISCOVERED",
"application": { "name": "Figma" }
}
]
}
}
}
Operations
GraphQL defines two main operation types:
- Queries — read data without side effects.
- Mutations — create, update, or delete data.
Browse the available queries and their related schema types in the area-based schema reference.
Error Handling
GraphQL errors are returned in the errors array alongside any partial data:
{
"errors": [
{
"message": "The current user is not authorized to access this resource.",
"path": ["applications"],
"extensions": {
"code": "AUTH_NOT_AUTHORIZED"
}
}
],
"data": {
"applications": null
}
}
Common error scenarios:
| Scenario | Example message |
|---|---|
| Invalid or missing API key | The current user is not authorized to access this resource. |
| Missing required argument | The argument 'id' is required. |
| Wrong argument type | The specified argument value does not match the argument type. |
| Unknown field | The field 'foo' does not exist on the type 'Query'. |