API Ingest

Journals and research systems can push gaps to gitgap directly via API. Two ingest directions: gitgap pulls from you (automated, preferred), or you push to gitgap (for systems with their own gap-extraction capability).

Full interactive API documentation is available at /api/docs. The endpoints below are the primary integration points for external systems.

Authentication

Push endpoints require an API key. Pass it in the request header:

X-API-Key: your-api-key-here

To register for an API key, submit your journal and request API access in the notes field. Rate limit: 100 requests/minute.

Ingest by PMC ID

The simplest ingest path — if the paper is in PubMed Central, provide the ID and gitgap handles extraction.

POST /ingest/pmcid
Content-Type: application/json
X-API-Key: your-key

{
  "pmcid": "PMC9876543",
  "catching_cosmoid": "optional-cosmoid-if-paper-is-catching-a-gap"
}

Returns: { "gap_ids": [42, 43], "paper_id": 91 }

Ingest from text (non-PMC papers)

For preprints, Zenodo papers, institutional repository content, or any paper without a PMC ID. Provide the text directly.

POST /ingest/from-text
Content-Type: application/json
X-API-Key: your-key

{
  "title": "Spatial indexing in criminal justice risk assessment",
  "abstract_text": "This study examines... Future research should...",
  "doi": "10.5281/zenodo.1234567",
  "year": 2024,
  "catching_cosmoid": "optional"
}

Returns: { "gap_ids": [44], "paper_id": 92 }

Pin a gap directly

If your system has already identified a gap and you want to register it in the index without running full extraction, pin it directly.

POST /gaps/pin
Content-Type: application/json
X-API-Key: your-key

{
  "declaration_text": "No study has examined the use of Morton encoding in predictive policing risk scores.",
  "gateway_term": "Morton encoding",
  "paper_pmcid": "PMC5777393",
  "catching_cosmoid": "optional"
}

Returns:

{
  "id": 45,
  "gateway_term": "Morton encoding",
  "source_discipline": "computer_science",
  "bridge_potential": 0.8,
  "status": "naught"
}

Seal a gap (FOUND)

When a paper addressing a gap is accepted or published, seal the lifecycle by calling the found endpoint. This sets found_at and moves the gap to FOUND state.

POST /gaps/{gap_id}/found
Content-Type: application/json
X-API-Key: your-key

{
  "found_paper_cosmoid": "cosmo-uuid-here",
  "found_paper_doi": "10.5281/zenodo.9876543"
}

Reject a gap attempt

When a resolution attempt fails peer review, record the rejection. The pickup instructions become public — this is the value of the rejected trail.

POST /gaps/{gap_id}/reject
Content-Type: application/json
X-API-Key: your-key

{
  "rejection_mode": "methodology",
  "rejection_notes": "Internal editorial note (not public)",
  "pickup_instructions": "Future attempts must address measurement validity using..."
}

Rejection modes

Mode	When to use
methodology	The approach was flawed or inappropriate for the gap
scope	The paper didn't fully address the declared gap
insufficient_evidence	Claims made without adequate empirical support
theory_gap	Theoretical framework was missing or incomplete
duplicate	A paper already closed this gap
other	Use notes to specify

Search the gap index

No API key required for read endpoints.

# Full-text search
GET /gaps/search?q=Morton+encoding&limit=10&min_score=0.5

# Structural holes (cross-discipline bridges)
GET /gaps/structural-holes?source=computer_science&target=criminal_justice&min_bridge=0.6

# Single gap
GET /gaps/42

# Bulk export (CSV)
GET /gaps/export.csv?verdict=pass&term=spatial

Webhook pattern (journal editorial systems)

If your journal's editorial system auto-assigns DOIs on acceptance, you can wire a webhook to seal the lifecycle automatically. On paper acceptance:

Your system calls POST /gaps/{gap_id}/found with the cosmoid and DOI
gitgap sets found_at, stores the DOI, moves the gap to FOUND
The globe updates on next load — the spike gains a gold ring

The gap_id is returned when the paper is first ingested (gap_ids[0] from the ingest response) and should be stored in your editorial system at submission time.