Agent API documentation

Connect a compatible AI agent.

Create and verify a ScholrQ account. The Free plan activates automatically after verification; sign in, then create a key in your dashboard. Use https://scholrq.com/api/agent/v1 for REST or https://scholrq.com/mcp for stateless Streamable HTTP MCP. Pilot support covers clients that can send a custom Authorization header. OAuth connection support comes later.

Install the ScholrQ agent skill

Download the ScholrQ skill ZIP or read its instructions. Add the ZIP’s folder to your agent’s skills directory. The skill guides the agent to use ScholrQ’s MCP tools, with REST as a fallback. It contains no API key; create a key in your dashboard and store it in your agent client’s secret settings. Skill use follows the same search-credit limits.

Automated signup

An agent can use the existing account API if you authorize it to use an email inbox. Keep the HTTP cookies between requests. First, POST {"confirmed":true} to /api/v1/adult-confirm to affirm the account owner is at least 18. Then POST name, email, and a 12–128 character password to /api/v1/account/signup. The verification email contains a link with a one-time token; POST that token to /api/v1/account/activate. The Free plan activates at that point. Sign in through /api/v1/account/signin with the same cookie jar, then POST a key label to /api/agent/keys. Its full key is returned once. Email verification cannot be skipped, and a mailbox owner may complete that step manually.

Authentication and quotas

Set Authorization: Bearer $SCHOLRQ_AGENT_KEY. Never put a key in a URL or tool argument. Successful searches, detail reads, comparisons, matches, change pages, and pagination requests use one credit. Authentication, validation, errors, documentation, tools/list, and usage checks do not. Free resets at 00:00 UTC on the first day of each month; paid plans follow the Stripe billing period. Credits do not roll over.

REST example

curl -H "Authorization: Bearer $SCHOLRQ_AGENT_KEY" \
  "https://scholrq.com/api/agent/v1/scholarships?country=CA&limit=10"

JavaScript example

const response = await fetch("https://scholrq.com/api/agent/v1/scholarships", {
  headers: { Authorization: "Bearer " + process.env.SCHOLRQ_AGENT_KEY }
});
const result = await response.json();

MCP example

{
  "url": "https://scholrq.com/mcp",
  "headers": { "Authorization": "Bearer $SCHOLRQ_AGENT_KEY" }
}

Responses and freshness

Every successful response contains data, requestId, and usage. Scholarship records include official URLs, evidence, verification status, verifiedOn, updatedAt, and a catalogue version. Unknown facts remain null. Errors use stable JSON codes with HTTP 400, 401, 403, 404, 429, or 500 and include a request ID. See OpenAPI JSON for the REST contract.

Use and attribution

Keep ScholrQ’s official-source links attached to scholarship answers and identify ScholrQ as the catalogue source. Do not share credentials, bulk extract the catalogue, resell raw results, submit applications, or bypass quotas. Matching is deterministic and stateless; ScholrQ does not store submitted matching profiles or run an LLM in v1.