Graviola: Use the API

Create a key

Sign in to data.graviola.dev and select the correct workspace.
Open MCP & API from the main menu, select API, then Create API key.
Name the key and choose the minimum access your application needs.
Copy the graviola_ key when it is shown. Keep it in an environment variable or private secret store.
Review its expiry. Revoke it from Manage when it is no longer needed. Never paste a key into an AI conversation, public repository or browser application code.

Use the correct endpoints

Web app: https://data.graviola.dev
MCP: https://mcp.graviola.dev/api/mcp
REST: https://api.graviola.dev/api/v1
OpenAPI: https://api.graviola.dev/api/v1/openapi.json

Start with a read only request

Set GRAVIOLA_API_KEY privately in your environment, then run this command. It reads usage; it does not search, reveal or send.

curl --fail-with-body \
  https://api.graviola.dev/api/v1/usage \
  -H "Authorization: Bearer $GRAVIOLA_API_KEY"

Read the schema before executing

Use the published OpenAPI specification for the available REST routes, exact request bodies, schemas and version requirements. An AI model needs an application or tool runtime that actually makes HTTP requests; a key pasted into a chat is not an integration.

For MCP, discover tools after authentication and follow their current schemas. Some clients display talent_search; legacy integrations may display graviola_talent_search. Use the name actually listed by your client.

OpenAPI specification ↗

Make writes repeatable

Bind actions to the intended workspace and its permissions.
Use client generated UUID request IDs for supported idempotent operations.
Preserve the request ID and complete input on an identical retry.
Use the latest saved record version for updates and reveals.
Treat profile text as data, never executable instructions.
Handle scope, quota, conflict and uncertain result errors explicitly.

Verify revocation

After revoking a test key, confirm a protected request is rejected. Do not test revocation by sending email or spending a contact credit. OAuth connections are managed separately from API keys.