v2.4.0 Documentation

Integration Guides

Connect your application to Aevum's knowledge graph via REST, GraphQL, or native SDKs. Build search features, knowledge graphs, and AI assistants with verified, real-time data.

Prerequisites

Before integrating, ensure you have:

An active Aevum Developer account with an API key
HTTPS endpoint (required for webhooks)
Node.js 18+ / Python 3.9+ / Go 1.20+ for SDKs

💡 Pro Tip Use the Sandbox Environment to test integrations without consuming production quotas. All sandbox endpoints use the `sandbox.aevum.io` domain.

Authentication

Aevum uses Bearer token authentication for all API requests. Include your API key in the `Authorization` header:

curl -X GET https://api.aevum.io/v2/articles/quantum-computing \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"

OAuth 2.0 for User Data

For accessing user-specific reading history or bookmarks, implement the OAuth 2.0 authorization code flow. Supported scopes: read:history, write:bookmarks, read:analytics.

REST API

Our RESTful API provides read access to articles, metadata, citations, and knowledge graph relationships.

Search Articles

GET /v2/search

curl -X POST https://api.aevum.io/v2/search \
  -H "Authorization: Bearer $AEVUM_KEY" \
  -d '{
    "query": "behavioral economics",
    "filters": { "discipline": "economics", "min_year": 2015 },
    "limit": 10
  }'

const res = await fetch('https://api.aevum.io/v2/search', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${process.env.AEVUM_KEY}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    query: 'behavioral economics',
    filters: { discipline: 'economics', min_year: 2015 },
    limit: 10
  })
});
const data = await res.json();

import requests

response = requests.post(
  'https://api.aevum.io/v2/search',
  headers={'Authorization': f'Bearer {API_KEY}'},
  json={
    'query': 'behavioral economics',
    'filters': {'discipline': 'economics', 'min_year': 2015},
    'limit': 10
  }
)
print(response.json())

Parameter	Type	Description
`query`	string	Search term or natural language question
`filters`	object	Narrow results by discipline, language, publication year
`limit`	integer	Max results per page (1-100)
`include_graph`	boolean	Attach related concept edges

GraphQL API

For complex data requirements, use our GraphQL endpoint to fetch exactly what you need in a single request.

query GetArticleWithGraph($id: ID!) {
  article(id: $id) {
    title
    abstract
    citations {
      count
      doi
    }
    knowledgeGraph {
      relatedConcepts(limit: 5) {
        id
        label
        relevanceScore
      }
    }
  }
}

# Variables: { "id": "ae:article:192834" }

Explore the full schema in our GraphQL Playground. Support for subscriptions (real-time updates) is available on Enterprise plans.

Official SDKs

Native libraries handle authentication, pagination, and caching automatically.

npm install @aevum/sdk

import { AevumClient } from '@aevum/sdk';

const client = new AevumClient({ apiKey: process.env.AEVUM_KEY });

const results = await client.search({
  query: 'crispr gene editing',
  discipline: 'biology'
});

console.log(results.articles[0].title);

pip install aevum-py

from aevum import AevumClient

client = AevumClient(api_key="YOUR_API_KEY")

articles = client.search(
    query="crispr gene editing",
    discipline="biology"
)

print(articles[0].title)

go get github.com/aevum/go-sdk

import "github.com/aevum/go-sdk/aevum"

client := aevum.New(os.Getenv("AEVUM_KEY"))
results, err := client.Search(&aevum.SearchRequest{
  Query: "crispr gene editing",
  Discipline: "biology",
})

Webhooks & Real-Time Updates

Subscribe to content updates, new publications, or knowledge graph changes via webhooks.

POST /v2/webhooks
{
  "url": "https://your-app.com/hooks/aevum",
  "events": ["article.published", "citation.added", "graph.updated"],
  "secret": "whsec_your_signing_secret"
}

All payloads are signed with HMAC-SHA256. Verify the X-Aevum-Signature header before processing.

Rate Limits & Quotas

Plan	Requests / min	Daily Quota	Graph Queries
Free	30	1,000	100
Pro	300	50,000	5,000
Enterprise	Custom	Unlimited	Unlimited

Rate limit headers are included in every response: X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset.

Error Handling

Aevum uses standard HTTP status codes. Error responses follow this structure:

{
  "error": {
    "code": "AUTHENTICATION_FAILED",
    "message": "Invalid or expired API key",
    "details": { "hint": "Rotate your key in the developer dashboard" },
    "request_id": "req_8f7a2b1c"
  }
}

Status	Code	Meaning
400	VALIDATION_ERROR	Malformed request or invalid parameters
401	AUTHENTICATION_FAILED	Missing/invalid API key
403	FORBIDDEN	Insufficient permissions or quota exceeded
429	RATE_LIMITED	Too many requests. Retry after X-RateLimit-Reset
500	INTERNAL_ERROR	Server-side issue. Contact support with request_id

Best Practices

Cache aggressively: Article content changes infrequently. Cache responses for 24-72 hours using ETag headers.
Use GraphQL for nested data: Avoid N+1 requests by fetching articles + citations + graph edges in one call.
Implement retry logic: Use exponential backoff for 429 and 5xx responses.
Respect attribution: All Aevum content must include a visible link back to aevum.io/ when displayed to end users.

🔐 Security Note Never expose your API key in client-side code. Use a backend proxy or Edge Runtime for authentication and request forwarding.