Departments

Read API

For your department’s IT staff: read the roster, CVs and reports into your own systems, server to server. Read only.

Read API 1.0.0 · ScienceDex app 1.26.0

Before you start

A department admin makes a token on the department’s Settings page, under API access, and chooses what it can read: the roster, CVs, reports, or more than one. It ends after 1 to 365 days, 90 unless they choose.
The token is shown once. Keep it in your system’s secret store, never in code, email or a shared document.
It reads with the rights of the person who made it, in that department and its divisions, at the moment of each call. If they stop running the department, the token stops.

Send the token

Send it on every request as Authorization: Bearer sdx_…. The API reads no cookies and sends no CORS headers, so a web page on another site cannot call it. A token in the address is refused.

curl https://sciencedex.com/api/v1/roster \
  -H "Authorization: Bearer $SCIENCEDEX_TOKEN"

Endpoints

Each answer is JSON, private and never stored by a cache.

Read API endpoints
Endpoint	Token can read	Returns
`GET /api/v1/roster`	Roster	Everyone in the department and its divisions: person ID, name, email, role, division, rank, track, and when the CV last changed. Never time in rank or review eligibility.
`GET /api/v1/cvs/{personId}`	CVs	One person’s CV as the department sees it, with the name of each section. Each read shows in that person’s activity.
`GET /api/v1/reports`	Reports	The built-in and saved reports, with what each gives this token.
`GET /api/v1/reports/{reportId}/rows`	Reports	One page of a report, with the same columns, labels, values and header as its Excel file.
`GET /api/v1/openapi.json`	No token needed	This API as an OpenAPI 3.1 document.

The roster

personId is the person ID the reports print (SDX-P- and six digits). It never changes. Someone invited who has not joined has none yet.

curl "https://sciencedex.com/api/v1/roster?limit=200" \
  -H "Authorization: Bearer $SCIENCEDEX_TOKEN"

One CV

status is ok, no_cv or needs_repair. cv holds the profile’s work contact details, the packet target, the entries and the narrative; entries hidden from the person’s Word files are in it, marked hiddenFromExport.

curl https://sciencedex.com/api/v1/cvs/SDX-P-123456 \
  -H "Authorization: Bearer $SCIENCEDEX_TOKEN"

Reports

A report’s id is a built-in report’s key, such as publications, or a saved report’s id from the list. When countsOnly is true, the report gives counts by rank, because the person who made the token does not see names in promotion data.

curl https://sciencedex.com/api/v1/reports \
  -H "Authorization: Bearer $SCIENCEDEX_TOKEN"

curl "https://sciencedex.com/api/v1/reports/publications/rows?limit=500" \
  -H "Authorization: Bearer $SCIENCEDEX_TOKEN"

Pages

Lists come a page at a time. Send limit for the page size and the last answer’s nextCursor as cursor, unchanged, until nextCursor is null.

curl "https://sciencedex.com/api/v1/roster?limit=200&cursor=$NEXT_CURSOR" \
  -H "Authorization: Bearer $SCIENCEDEX_TOKEN"

Roster pages hold up to 500 people (100 by default), the report list up to 200 (100), and report rows up to 1,000 (500). A report is built again for each page, so rows that change between pages can shift.

Limits

60 requests a minute per token, on every endpoint together. Each answer says how many are left in RateLimit-Remaining and when the count starts again in RateLimit-Reset, in seconds.
Past the limit the answer is 429, with Retry-After in seconds.
A report runs up to 20,000 rows. A page of rows stays under 4 MB, so it may hold fewer rows than the limit asks for; follow nextCursor.

Errors

Every error is JSON with a code your system can check and a message for a person.

{
  "code": "token_expired",
  "message": "This token has ended. Ask a department admin for a new one."
}

Errors and their codes
Status	Code	When
400	`token_in_url`	The token was in the address. Send it only in the Authorization header.
400	`invalid_limit, invalid_cursor`	A limit out of range, or a cursor this endpoint did not give. Start again without one.
401	`token_missing`	No Authorization: Bearer header. Cookies never count.
401	`token_invalid`	Not a ScienceDex token, or no such token. Check it was copied whole.
401	`token_revoked`	An admin revoked it.
401	`token_expired`	Its end date has passed.
401	`token_no_access`	The person who made it no longer runs the department, or has left.
403	`insufficient_scope`	The token cannot read this; scope names what it needs.
404	`not_found, person_not_found, report_not_found`	No such endpoint, no such active member of the department, or no such report.
405	`method_not_allowed`	The API only answers GET.
409	`report_definition_invalid, report_group_missing, report_division_missing`	A saved report that can no longer run. An admin fixes it in the report builder.
413	`report_too_large`	The report is past the limits below; reason says which.
429	`rate_limited`	Too many requests this minute. Wait Retry-After seconds.
500	`server_error`	Something failed, the log included, so nothing was sent. Try again.
503	`unavailable`	The API is not available on this deployment.

What the API never gives

No home addresses, personal phones, private notes or entries a person marks private.
Named people in promotion data only for a token made by the chair or the vice chair for faculty affairs, or a role the department adds. Everyone else gets counts by rank, with 1 to 4 people shown as “fewer than 5”.
Every CV read and report page is logged. Faculty see which token read their CV and who made it.

OpenAPI document Data limits in full