Search Platform API Documentation

Authentication

Login

Authenticate to obtain a JWT token that's required for all other endpoints.

Endpoint: /auth/login Method: POST
Content-Type: application/json

Request Body

{
  "username": "your_username",
  "password": "your_password"
}

Response

Success (200 OK)

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "user": {
    "id": 123,
    "username": "your_username",
    "email": "user@example.com",
    "role": "user_role"
  }
}

Error Responses

• 400 Bad Request: Missing required fields
• 401 Unauthorized: Invalid credentials
• 500 Internal Server Error: Database or token generation error

Notes

• The token expires after 24 hours
• Store this token securely for subsequent requests

Search

Execute Search

Perform a search across specified engines.

Endpoint: /search Method: POST
Content-Type: application/json
Authorization: Bearer {token}

Request Body

{
  "term": "search_term",
  "universe": ["term1", "term2"],
  "engines": ["engine1", "engine2"],
  "analysis": false
}

Parameters

Field	Type	Required	Description
term	string	Yes	The search term
engines	string[]	Yes	List of search engines to query
universe	string[]	Yes	List of terms defining the search universe
analysis	boolean	No	Enable analysis mode

Response

Success (200 OK)

[
  {
    // Search results structure depends on the engine implementation
  }
]

Error Responses

• 400 Bad Request: Missing required fields
• 401 Unauthorized: Missing or invalid token
• 500 Internal Server Error: Search execution error

Usage Example

# 1. Authenticate and get token
curl -X POST https://platform.energesis.es/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"username": "your_username", "password": "your_password"}'

# Response will contain your token

# 2. Execute a search
curl -X POST https://platform.energesis.es/api/search \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{
    "term": "example search",
    "engines": ["doaj", "arxiv"],
    "universe": ["related term 1", "related term 2"],
    "analysis": true
  }'

info

If analysis is True it will only search the combination of term AND universe, this is the desired behavior for matrix calculation. If analysis is False it will search term, universe, and the combination of both, this is the desired behavior to calculate projections and other stats.