Search API Documentation

Authentication
Base URL
Endpoints
- Papers
- Jobs
- User
CallBacks
Error Handling
Examples

Authentication

All API endpoints require authentication using an API key. Include your API key in the Authorization header:

Authorization: Bearer YOUR_API_KEY

Base URL

The base URL for all API endpoints is:

https://discover.veritus.ai/api

Endpoints

→ Papers

GET `/v1/papers/search`

Search for papers by title. Headers:

Authorization (required): Bearer token with your API key (format: Bearer YOUR_API_KEY)

Query Parameters:

title (required): The title of the paper to search for

Response:

200 OK: Returns an array of matching papers

Response Structure:

[
  {
    "abstract": "Paper abstract text or null",
    "authors": "Author1, Author2, Author3",
    "doi": "10.1234/example.doi",
    "downloadable": true,
    "engine": "ss-veritus",
    "fieldsOfStudy": ["Computer Science", "Mathematics"],
    "id": "paper_id_string",
    "impactFactor": {
      "citationCount": 150,
      "influentialCitationCount": 25,
      "referenceCount": 50
    },
    "isOpenAccess": true,
    "isPrePrint": false,
    "journalName": "Journal Name",
    "link": "https://example.com/paper",
    "pdfLink": "https://example.com/paper.pdf",
    "publicationType": "journal",
    "publishedAt": "2023-01-15",
    "score": 0.95,
    "semanticLink": "https://semanticscholar.org/paper/123",
    "title": "Paper Title",
    "titleLink": "https://example.com/paper",
    "tldr": "TLDR summary of the paper",
    "v_country": "United States",
    "v_journal_name": "Journal Name",
    "v_publisher": "Publisher Name",
    "v_quartile_ranking": "Q1",
    "year": 2023
  }
]

Response Fields:

abstract: Paper abstract text (string or null)
authors: Comma-separated list of author names (string)
doi: Digital Object Identifier (string or null)
downloadable: Whether the paper PDF is downloadable (boolean)
engine: Search engine used (string, optional)
fieldsOfStudy: Array of field of study categories (string array)
id: Unique paper identifier (string)
impactFactor: Object containing citation metrics:
- citationCount: Total number of citations (number)
- influentialCitationCount: Number of influential citations (number)
- referenceCount: Number of references (number)
isOpenAccess: Whether the paper is open access (boolean, optional)
isPrePrint: Whether the paper is a preprint (boolean, optional)
journalName: Name of the journal (string or null)
link: URL to the paper (string, optional)
pdfLink: URL to the PDF (string, optional)
publicationType: Type of publication (string or null)
publishedAt: Publication date (string or null)
score: Relevance score (number or null)
semanticLink: Link to Semantic Scholar page (string, optional)
title: Paper title (string)
titleLink: Link to paper title page (string, optional)
tldr: TLDR summary (string or null)
v_country: Country of publication venue (string or null)
v_journal_name: Journal name from venue data (string or null)
v_publisher: Publisher name (string or null)
v_quartile_ranking: Quartile ranking (Q1, Q2, Q3, Q4, or null)
year: Publication year (number or null)

Example:

curl -X GET "https://discover.veritus.ai/api/v1/papers/search?title=Machine%20Learning" \
  -H "Authorization: Bearer YOUR_API_KEY"

GET `/v1/papers/{corpusId}`

Get a paper by its corpus ID. Headers:

Authorization (required): Bearer token with your API key (format: Bearer YOUR_API_KEY)

Path Parameters:

corpusId (required): The corpus ID of the paper

Response:

200 OK: Returns paper details

Response Structure:

{
  "abstract": "Paper abstract text or null",
  "authors": "Author1, Author2, Author3",
  "doi": "10.1234/example.doi",
  "downloadable": true,
  "engine": "ss-veritus",
  "fieldsOfStudy": ["Computer Science", "Mathematics"],
  "id": "paper_id_string",
  "impactFactor": {
    "citationCount": 150,
    "influentialCitationCount": 25,
    "referenceCount": 50
  },
  "isOpenAccess": true,
  "isPrePrint": false,
  "journalName": "Journal Name",
  "link": "https://example.com/paper",
  "pdfLink": "https://example.com/paper.pdf",
  "publicationType": "journal",
  "publishedAt": "2023-01-15",
  "score": 0.95,
  "semanticLink": "https://semanticscholar.org/paper/123",
  "title": "Paper Title",
  "titleLink": "https://example.com/paper",
  "tldr": "TLDR summary of the paper",
  "v_country": "United States",
  "v_journal_name": "Journal Name",
  "v_publisher": "Publisher Name",
  "v_quartile_ranking": "Q1",
  "year": 2023
}

Response Fields: See the Response Fields section under GET /v1/papers/search for detailed field descriptions. Example:

curl -X GET "https://discover.veritus.ai/api/v1/papers/12345678" \
  -H "Authorization: Bearer YOUR_API_KEY"

→ Jobs

POST `/v1/job/{jobType}`

Create a new search job. Jobs are asynchronous operations that can be checked for status later. Headers:

Authorization (required): Bearer token with your API key (format: Bearer YOUR_API_KEY)
Content-Type: application/json

Path Parameters:

jobType (required): Type of job to create. Must be one of:
- keywordSearch: Search using phrases
- querySearch: Search using a query string
- combinedSearch: Search using both phrases and query

Query Parameters:

limit (optional): Maximum number of results. Must be 100, 200, or 300. Default: 100
fieldsOfStudy (optional): Comma-separated list of fields of study. Valid values:
- Computer Science
- Medicine
- Chemistry
- Biology
- Materials Science
- Physics
- Geology
- Psychology
- Art
- History
- Geography
- Sociology
- Business
- Political Science
- Economics
- Philosophy
- Mathematics
- Engineering
- Environmental Science
- Agricultural and Food Sciences
- Education
- Law
- Linguistics
minCitationCount (optional): Minimum number of citations. Must be a positive integer.
openAccessPdf (optional): Filter for open access PDFs. Must be true or false.
downloadable (optional): Filter for downloadable papers. Must be true or false.
quartileRanking (optional): Filter by quartile ranking(s). Can be a single value or comma-separated list. Valid values: Q1, Q2, Q3, Q4. Example: Q1 or Q1,Q2,Q3
publicationTypes (optional): Comma-separated list of publication types. Valid values:
- journal
- book series
- conference
sort (optional): Sort order. Format: field:direction. Valid fields:
- score
- citationCount
- influentialCitationCount
- quartileRanking
- referenceCount
- year
year (optional): Filter by year. Format: YYYY (single year) or YYYY:YYYY (year range). Example: 2020 or 2020:2023

Request Body:

{
  "callbackUrl": "https://your-domain.com/webhook", // Optional: HTTPS URL for job completion callback
  "enrich": false, // Optional: Whether to enrich results. Default: false
  "phrases": ["phrase1", "phrase2", "phrase3"], // Required for keywordSearch and combinedSearch. Must have 3-10 phrases
  "query": "Your search query here" // Required for querySearch and combinedSearch. Must be 50-5000 characters
}

Job Type Requirements:

keywordSearch: Requires phrases (3-10 phrases)
querySearch: Requires query (50-5000 characters)
combinedSearch: Requires either phrases (3-10 phrases) OR query (50-5000 characters), or both

Credits Deduction: Credits are automatically deducted when a job is created. The deduction happens before the job is queued:

Credits Calculation: Credits deducted = Math.ceil(limit / 100)
- Example: limit=100 → 1 credit, limit=200 → 2 credits, limit=300 → 3 credits
Credit Tier:
- If enrich=true: Uses Pro Tier Credits (higherTierCreditsBalance)
- If enrich=false: Uses Free Tier Credits (lowerTierCreditsBalance)
Insufficient Credits: If you don’t have enough credits, the request will fail with a 403 Forbidden error:
```
{
  "error": "Insufficient credits"
}
```
Response:
200 OK: Returns job creation response with job ID:
```
{
  "jobId": "507f1f77bcf86cd799439011"
}
```
403 Forbidden: Insufficient credits

Example - Keyword Search:

curl -X POST "https://discover.veritus.ai/api/v1/job/keywordSearch?limit=100&fieldsOfStudy=Computer%20Science&minCitationCount=10" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "phrases": ["machine learning", "neural networks", "deep learning"],
    "callbackUrl": "https://your-domain.com/webhook",
    "enrich": true
  }'

Example - Query Search:

curl -X POST "https://discover.veritus.ai/api/v1/job/querySearch?limit=200&year=2020:2023" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "This is a detailed query about machine learning and artificial intelligence that describes what you are looking for in academic papers.",
    "callbackUrl": "https://your-domain.com/webhook"
  }'

Example - Combined Search:

curl -X POST "https://discover.veritus.ai/api/v1/job/combinedSearch?limit=300&openAccessPdf=true&quartileRanking=Q1,Q2&sort=citationCount:desc" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "phrases": ["natural language processing", "transformer models", "BERT"],
    "query": "Recent advances in transformer-based models for natural language understanding and generation",
    "callbackUrl": "https://your-domain.com/webhook",
    "enrich": true
  }'

→ GET `/v1/job/{jobId}`

Get the status of a job by its job ID. Headers:

Authorization (required): Bearer token with your API key (format: Bearer YOUR_API_KEY)

Path Parameters:

jobId (required): The job ID returned from job creation

Response:

200 OK: Returns job status and results (if completed)

Response Structure: When status is queued:

{
  "status": "queued"
}

When status is error:

{
  "status": "error"
}

When status is success:

{
  "status": "success",
  "results": [
    {
      "abstract": "Paper abstract text or null",
      "authors": "Author1, Author2, Author3",
      "doi": "10.1234/example.doi",
      "downloadable": true,
      "engine": "ss-veritus",
      "fieldsOfStudy": ["Computer Science", "Mathematics"],
      "id": "paper_id_string",
      "impactFactor": {
        "citationCount": 150,
        "influentialCitationCount": 25,
        "referenceCount": 50
      },
      "isOpenAccess": true,
      "isPrePrint": false,
      "journalName": "Journal Name",
      "link": "https://example.com/paper",
      "pdfLink": "https://example.com/paper.pdf",
      "publicationType": "journal",
      "publishedAt": "2023-01-15",
      "score": 0.95,
      "semanticLink": "https://semanticscholar.org/paper/123",
      "title": "Paper Title",
      "titleLink": "https://example.com/paper",
      "tldr": "TLDR summary of the paper",
      "v_country": "United States",
      "v_journal_name": "Journal Name",
      "v_publisher": "Publisher Name",
      "v_quartile_ranking": "Q1",
      "year": 2023
    }
  ]
}

Response Fields:

status: Job status. Possible values:
- queued: Job is queued for processing
- success: Job completed successfully
- error: Job failed with an error
results: Array of paper results (only present when status is success). Each result follows the same structure as described in the Response Fields section under GET /v1/papers/search.

Example:

curl -X GET "https://discover.veritus.ai/api/v1/job/507f1f77bcf86cd799439011" \
  -H "Authorization: Bearer YOUR_API_KEY"

→ User

GET `/v1/user/getCredits`

Get your current credit balance and plan information. Headers:

Authorization (required): Bearer token with your API key (format: Bearer YOUR_API_KEY)

Response:

200 OK: Returns credit balance information:

{
  "proTierCreditsBalance": 50,
  "proTierCreditsTotal": 100,
  "freeTierCreditsBalance": 75,
  "freeTierCreditsTotal": 100,
  "plan": "free"
}

Response Fields:

proTierCreditsBalance: Current balance of Pro Tier credits (used when enrich=true)
proTierCreditsTotal: Total Pro Tier credits ever allocated
freeTierCreditsBalance: Current balance of Free Tier credits (used when enrich=false)
freeTierCreditsTotal: Total Free Tier credits ever allocated
plan: Your current plan (e.g., “free”, “pro”)

Example:

curl -X GET "https://discover.veritus.ai/api/v1/user/getCredits" \
  -H "Authorization: Bearer YOUR_API_KEY"

Note: Check your credits before creating jobs to ensure you have sufficient balance. Credits are deducted immediately upon job creation.

Callbacks

When creating a job, you can optionally provide a callbackUrl to receive a notification when the job completes. This allows you to avoid polling the job status endpoint.

Setting Up Callbacks

To enable callbacks, include a callbackUrl field in your job creation request body:

{
  "callbackUrl": "https://your-domain.com/webhook",
  "phrases": ["machine learning", "neural networks", "deep learning"]
}

Callback URL Requirements

Protocol: Must be HTTPS (HTTP and localhost URLs are not allowed)
Format: Must be a valid URL
Example: https://api.example.com/webhooks/veritus

Callback Payload

When a job completes successfully, a POST request will be sent to your callback URL with the following JSON payload:

{
  "data": [
    {
      "abstract": "Paper abstract text or null",
      "authors": "Author1, Author2, Author3",
      "doi": "10.1234/example.doi",
      "downloadable": true,
      "engine": "ss-veritus",
      "fieldsOfStudy": ["Computer Science", "Mathematics"],
      "id": "paper_id_string",
      "impactFactor": {
        "citationCount": 150,
        "influentialCitationCount": 25,
        "referenceCount": 50
      },
      "isOpenAccess": true,
      "isPrePrint": false,
      "journalName": "Journal Name",
      "link": "https://example.com/paper",
      "pdfLink": "https://example.com/paper.pdf",
      "publicationType": "journal",
      "publishedAt": "2023-01-15",
      "score": 0.95,
      "semanticLink": "https://semanticscholar.org/paper/123",
      "title": "Paper Title",
      "titleLink": "https://example.com/paper",
      "tldr": "TLDR summary of the paper",
      "v_country": "United States",
      "v_journal_name": "Journal Name",
      "v_publisher": "Publisher Name",
      "v_quartile_ranking": "Q1",
      "year": 2023
    }
  ],
  "event": {
    "api_version": "v1",
    "createdAt": "2024-01-15T10:30:00.000Z",
    "id": "result_id_string"
  },
  "job": {
    "id": "507f1f77bcf86cd799439011"
  }
}

Callback Payload Fields

data: Array of paper results (same structure as the results field in the job status response)
event: Event metadata:
- api_version: API version used (currently “v1”)
- createdAt: ISO 8601 timestamp when the result was created
- id: Unique result identifier
job: Job information:
- id: The job ID that was returned when creating the job

Callback Behavior

When Sent: Callbacks are only sent when a job completes successfully (status: "success")
Retries: The system automatically retries failed callback requests
No Callback on Error: If a job fails (status: "error"), no callback will be sent
HTTP Method: Callbacks are sent via POST request
Content-Type: The request body is JSON with Content-Type: application/json

Handling Callbacks

Your callback endpoint should:

Return 200 OK: Respond with a 200 status code to acknowledge receipt
Process Quickly: Keep processing time under 10 seconds to avoid timeouts
Handle Duplicates: Be idempotent - the same callback may be sent multiple times due to retries
Validate Job ID: Verify the job.id matches a job you created
Store Results: Save the results data for later retrieval

Example Callback Handler

Here’s an example of a simple callback handler:

// Express.js example
app.post("/webhook", async (req, res) => {
  try {
    const { data, event, job } = req.body;

    // Validate job ID
    const jobRecord = await findJobById(job.id);
    if (!jobRecord) {
      return res.status(404).json({ error: "Job not found" });
    }

    // Store results
    await saveJobResults(job.id, data);

    // Update job status in your system
    await updateJobStatus(job.id, "completed");

    // Return 200 to acknowledge receipt
    res.status(200).json({ received: true });
  } catch (error) {
    console.error("Error processing callback:", error);
    // Still return 200 to prevent retries for application errors
    res.status(200).json({ received: true, error: "Processing failed" });
  }
});

Testing Callbacks

To test callbacks locally, you can use services like:

ngrok - Create HTTPS tunnels to localhost
webhook.site - Temporary webhook URLs for testing
RequestBin - HTTP request inspector

Note: Localhost URLs are not accepted. You must use a publicly accessible HTTPS endpoint.

Error Handling

All endpoints return standard HTTP status codes:

200 OK: Request successful
400 Bad Request: Invalid request parameters or body
401 Unauthorized: Missing or invalid API key
404 Not Found: Resource not found
500 Internal Server Error: Server error

Error responses follow this format:

{
  "error": [
    {
      "message": "Error message description",
      "path": "field.path"
    }
  ]
}

Common Error Scenarios

Missing API Key:
```
{
  "error": "API key is required"
}
```

Invalid Parameters:

{
  "error": [
    {
      "message": "At least 3 and at most 10 phrases are required",
      "path": "phrases"
    }
  ]
}

Invalid Callback URL:

{
  "error": [
    {
      "message": "Callback URL must be a valid HTTPS URL",
      "path": "callbackUrl"
    }
  ]
}

Insufficient Credits:
```
{
  "error": "Insufficient credits"
}
```
This error occurs when creating a job and you don’t have enough credits in the appropriate tier (Pro Tier for enriched searches, Free Tier for non-enriched searches).

Examples

Complete Workflow: Check Credits, Create Job, and Check Status

# Step 1: Check your credit balance
curl -X GET "https://discover.veritus.ai/api/v1/user/getCredits" \
  -H "Authorization: Bearer YOUR_API_KEY"

# Step 2: Create a keyword search job (credits will be deducted)
JOB_RESPONSE=$(curl -X POST "https://discover.veritus.ai/api/v1/job/keywordSearch?limit=100" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "phrases": ["machine learning", "neural networks", "deep learning"],
    "callbackUrl": "https://your-domain.com/webhook"
  }')

# Extract job ID from response (example)
JOB_ID="507f1f77bcf86cd799439011"

# Step 3: Check job status
curl -X GET "https://discover.veritus.ai/api/v1/job/$JOB_ID" \
  -H "Authorization: Bearer YOUR_API_KEY"

Search with Multiple Filters

curl -X POST "https://discover.veritus.ai/api/v1/job/combinedSearch?limit=200&fieldsOfStudy=Computer%20Science,Mathematics&minCitationCount=50&openAccessPdf=true&quartileRanking=Q1,Q2,Q3&year=2020:2023&sort=citationCount:desc" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "phrases": ["artificial intelligence", "machine learning", "deep learning"],
    "query": "Recent advances in AI and machine learning research",
    "enrich": true
  }'

Get Paper Details and Citations

# Get paper details
curl -X GET "https://discover.veritus.ai/api/v1/papers/12345678" \
  -H "Authorization: Bearer YOUR_API_KEY"

Notes

Callback URLs: Must be valid HTTPS URLs. Localhost URLs are not allowed.
Query Length: For query and combined searches, queries must be between 50 and 5000 characters.
Phrases: For keyword and combined searches, you must provide between 3 and 10 phrases.
Rate Limiting: API rate limits may apply 10req/min.
Job Processing: Jobs are processed asynchronously. Use the callback URL or poll the job status endpoint to check completion.
Field Names: Field names in query parameters are case-sensitive. Use exact values as specified in the documentation.
Credits System:
- Credits are deducted immediately when a job is created (before queuing)
- Credits required = Math.ceil(limit / 100) (e.g., limit 100 = 1 credit, limit 200 = 2 credits, limit 300 = 3 credits)
- Pro Tier credits are used when enrich=true, Free Tier credits when enrich=false
- Always check your credit balance using /v1/user/getCredits before creating jobs
- If job creation fails due to insufficient credits, no credits are deducted

Contact and Support

Need help or onboarding support? Email: [email protected]
Website: www.veritus.ai
Offices: Tokyo & Kobe, Japan Veritus is backed by academic and government partners including JETRO, OIST Innovation Accelerator, and Lifetime Ventures Japan.

Getting started

Learn

Table of Contents

Authentication

Base URL

Endpoints

→ Papers

GET `/v1/papers/search`

GET `/v1/papers/{corpusId}`

→ Jobs

POST `/v1/job/{jobType}`

→ GET `/v1/job/{jobId}`

→ User

GET `/v1/user/getCredits`

Callbacks

Setting Up Callbacks

Callback URL Requirements

Callback Payload

Callback Payload Fields

Callback Behavior

Handling Callbacks

Example Callback Handler

Testing Callbacks

Error Handling

Common Error Scenarios

Examples

Complete Workflow: Check Credits, Create Job, and Check Status

Search with Multiple Filters

Get Paper Details and Citations

Notes

Contact and Support

Getting started

Learn

​Table of Contents

​Authentication

​Base URL

​Endpoints

​→ Papers

​GET /v1/papers/search

​GET /v1/papers/{corpusId}

​→ Jobs

​POST /v1/job/{jobType}

​→ GET /v1/job/{jobId}

​→ User

​GET /v1/user/getCredits

​Callbacks

​Setting Up Callbacks

​Callback URL Requirements

​Callback Payload

​Callback Payload Fields

​Callback Behavior

​Handling Callbacks

​Example Callback Handler

​Testing Callbacks

​Error Handling

​Common Error Scenarios

​Examples

​Complete Workflow: Check Credits, Create Job, and Check Status

​Search with Multiple Filters

​Get Paper Details and Citations

​Notes

​Contact and Support

Table of Contents

Authentication

Base URL

Endpoints

→ Papers

GET `/v1/papers/search`

GET `/v1/papers/{corpusId}`

→ Jobs

POST `/v1/job/{jobType}`

→ GET `/v1/job/{jobId}`

→ User

GET `/v1/user/getCredits`

Callbacks

Setting Up Callbacks

Callback URL Requirements

Callback Payload

Callback Payload Fields

Callback Behavior

Handling Callbacks

Example Callback Handler

Testing Callbacks

Error Handling

Common Error Scenarios

Examples

Complete Workflow: Check Credits, Create Job, and Check Status

Search with Multiple Filters

Get Paper Details and Citations

Notes

Contact and Support