SEIPID API

Version 1

What can the SEIPID API do?

Every registered scholarly platform has a persistent NiD, and every registered scholarly work has a persistent SEIPID. The SEIPID API answers in the keys of the SEIPID Metadata Schema 1.0, so the same JSON is used for reading and for writing. All addresses start with https://seipid.com/api/v1.

Read: no key

One record by its SEIPID
One platform by its NiD
The records of a platform, 50 a page

Up to 60 calls a minute from one computer. An answer may be up to 5 minutes old.

Write: an API key for one NiD

Issue a SEIPID
Update a record
Fix the target page and PDF links

The same plan, SEIPID balance, required fields, duplicate check and edit rules as the SEIPID Diwan portal.

Addresses

Which addresses does the API have?

Method	Address	Answer	Key
GET	`/api/v1/records/{seipid}`	The record in the schema's keys	No
GET	`/api/v1/platforms/{nid}`	The platform in the schema's keys	No
GET	`/api/v1/platforms/{nid}/records?page=1`	Its records, newest first, 50 a page	No
GET	`/api/v1/key`	The NiD and platform of your key, and your server address	Yes
POST	`/api/v1/records`	Issues a SEIPID for the record sent	Yes
PUT	`/api/v1/records/{seipid}`	Replaces the record with the whole record sent	Yes
PUT	`/api/v1/records/{seipid}/links`	Fixes `outputTargetPageLink` and `outputPdfLink`	Yes

curl https://seipid.com/api/v1/records/001:xijir:2025n4
curl https://seipid.com/api/v1/platforms/001:xijir
curl "https://seipid.com/api/v1/platforms/001:xijir/records?page=2"

API keys

How do you get and use an API key?

Make a keyIn the SEIPID Diwan portal, open Namespaces, the menu of your active namespace, then API Keys. The Account Admin and Managers can make keys.
Copy it onceThe key is shown only once. Keep it in your platform's settings, never in a web page or a shared file.
Send it with each callSend Authorization: Bearer <key>. If your server drops that header, send X-SEIPID-Key: <key>.
Check the connectionCall GET /api/v1/key. It answers with the NiD and the name of your platform.

Live and Test keys

A Live key saves. A Test key runs every check and saves nothing, so you can try your connection safely.

One key, one NiD

A key works only for its own NiD. Each record you send must name that NiD in nid. A key cannot sign in to the SEIPID Diwan portal.

Server lock

You can list your server addresses on the key. The key then works only from those servers. The Account Admin gets an email when a key is used from a new server.

Limits and cancel

200 write calls a day and 30 a minute for each key. Cancel a key in API Keys at any time: it stops working at once.

Issuing

How do you issue a SEIPID?

Send the record as JSON (1 MB at most). Leave out seipid: SEIPID gives it. Fields follow the metadata requirements of the content type.

curl -X POST https://seipid.com/api/v1/records \
  -H "Authorization: Bearer seipid_live_…" \
  -H "Content-Type: application/json" \
  -d @record.json

{
  "schemaVersion": "1.0",
  "nid": "014:exu-ir",
  "outputContentType": "thesis",
  "outputLanguage": ["en"],
  "outputOriginalTitle": "Code-Switching in Urdu-English Classroom Talk",
  "outputAbstractOrDescription": [
    { "language": "en", "text": "This thesis examines …" }
  ],
  "outputKeywords": ["code-switching", "classroom discourse", "Urdu"],
  "outputSubjectGroup": "humanities_arts",
  "outputDisciplines": ["languages_literature"],
  "outputContributors": [
    {
      "outputContributorType": "individual",
      "outputContributorGivenNames": "Ayesha",
      "outputContributorFamilyName": "Khan",
      "outputContributorRole": "author",
      "outputCorrespondingAuthor": true,
      "outputContributorAffiliation": {
        "outputAffiliationName": "Example University",
        "outputAffiliationCountry": "PK"
      },
      "orcid": "https://orcid.org/0000-0002-1825-0097"
    }
  ],
  "outputPublicationDate": "2024-09-15",
  "outputTargetPageLink": "https://repository.example.edu/handle/123/456",
  "outputAccessModel": "open_access",
  "outputLicence": "cc_by_nc_4_0",
  "outputOtherIdentifiers": [
    { "outputIdentifierType": "local_id", "outputIdentifierValue": "456" }
  ],
  "outputDegree": "Master of Philosophy",
  "outputAwardingInstitution": { "outputAwardingInstitutionName": "Example University" }
}

Sent twice by mistake?

Send your platform's own record ID as an Other Identifier of type local_id. If the same record arrives again, the answer gives back the SEIPID issued the first time.

Chapters and papers

For a chapter of a book or a paper of proceedings, add a related work of type is_part_of with the SEIPID of the book or proceedings on the same NiD.

Possible duplicates

If a similar record exists, the answer lists it. To issue anyway, send the call again with ?confirmDuplicate=true.

Links off your website

A target or PDF link outside your platform website waits for SEIPID approval. Until then the SEIPID opens its record page on seipid.com.

HTTP 201
{
  "seipid": "014:exu-ir:2024n12",
  "nid": "014:exu-ir",
  "status": "issued",
  "message": "SEIPID issued.",
  "linkWaiting": false,
  "record": "https://seipid.com/registry/014:exu-ir:2024n12"
}

HTTP 422
{
  "error": {
    "code": "invalid_record",
    "message": "Please correct the fields listed.",
    "fields": { "outputKeywords": "Add at least 3 keywords (max 7) for this content type." }
  }
}

Answers

What do the error codes mean?

Every error has the same shape: {"error": {"code", "message"}}. A record with mistakes also lists fields by their schema keys.

HTTP	Code	Meaning
400	`invalid_json`, `refused`	The body is not one JSON object, or the request cannot be done
401	`key_required`, `invalid_key`, `key_cancelled`	No key, a wrong key, or a cancelled key
403	`wrong_nid`, `server_not_allowed`, `not_allowed`, `key_not_active`	The key cannot do this: another NiD, a server outside its lock, or a key that can no longer be used
403	`plan`, `edit_limit`, `removed`	The plan or SEIPID balance does not allow it, the record has no edits left, or the record was removed
404	`not_found`	No such SEIPID, NiD or address
409	`possible_duplicate`	A similar record exists; see `matches`
413, 415	`too_large`, `wrong_content_type`	Over 1 MB, or not sent as JSON
422	`invalid_record`	Fields to correct, listed in `fields`
429	`too_many_requests`, `daily_limit`	Too many calls; wait for the seconds in `Retry-After`
500, 503	`server_error`, `not_ready`	Please try again later

Frequently Asked Questions (FAQs)

Where do I get an API key?

Open the SEIPID Diwan portal, go to Namespaces, open the menu of your active namespace and choose API Keys. The Account Admin and Managers can make a key. Each key works for one NiD only.

Open the SEIPID Diwan portal

What if I lose my key or someone else sees it?

A key is shown only once. If it is lost or seen by someone else, cancel it in API Keys and make a new one. A cancelled key stops working at once.

Can I test my connection without issuing a SEIPID?

Yes. Make a Test key. It runs every check on your record and answers as a live key would, but nothing is saved and no SEIPID is used.

Are the rules the same as in the Diwan portal?

Yes. A SEIPID issued through the API needs the same active plan, available SEIPIDs, active namespace and required fields as a SEIPID issued in the Diwan portal. Edits follow the same edit rules.

SEIPID metadata requirements

Do I need a key to read records?

No. Records and platforms can be read without a key, up to 60 calls a minute from one computer.

What is the server lock?

You can list the addresses of your platform server on the key. The key then works only from those servers. Call /api/v1/key from your server to see the address SEIPID receives.