COKI Open Access Dashboard API

openapi: 3.1.0
info:
  title: COKI Open Access Dashboard API
  version: '1.0'
  summary: Curtin Open Knowledge Initiative's public open-access analytics API covering ~60,000 institutions and every country.
  description: >-
    The Curtin Open Knowledge Initiative (COKI) is a research programme of Curtin University. It
    publishes the COKI Open Access Dashboard at https://open.coki.ac, backed by a keyless,
    CORS-open JSON API at https://api.coki.ac that serves open-access performance statistics for
    60,562 institutions and every country, with a 26-year time series per entity.

    This is the most substantial machine-readable surface Curtin itself operates. It is not a
    vendor product running under Curtin's name: the data pipeline is Curtin's Academic Observatory
    (github.com/The-Academic-Observatory) and the dashboard and API are the Curtin Open Knowledge
    Initiative's (github.com/Curtin-Open-Knowledge-Initiative). The `coki.ac` domain is COKI's own
    rather than a curtin.edu.au subdomain, which is why a hostname-only operator test misses it.

    Curtin publishes no OpenAPI description of this API and no developer documentation for it. This
    document was DERIVED by probing the live endpoints on 2026-08-30; every path, parameter and
    response field below was observed in an actual keyless response.
  contact:
    name: Curtin Open Knowledge Initiative
    url: https://open.coki.ac/
  x-operator: institution
  x-operator-evidence: >-
    "Curtin Open Knowledge Initiative" is the registered GitHub organisation
    (github.com/Curtin-Open-Knowledge-Initiative, 21 public repositories, described as "Code and
    resources from the Curtin Open Knowledge Initiative"); open.coki.ac links donations to
    curtin.edu.au/make-a-gift; the underlying pipeline is github.com/The-Academic-Observatory,
    Curtin's Academic Observatory. No other institution operates or shares this host.
  x-provenance:
    method: derived
    generated: '2026-08-30'
    source:
      - https://api.coki.ac/search/curtin
      - https://api.coki.ac/institutions?limit=2
      - https://api.coki.ac/countries
      - https://api.coki.ac/institution/02n415q13
      - https://api.coki.ac/country/AUS
    note: >-
      Derived from live keyless probes. api.coki.ac publishes no OpenAPI, no /docs and no
      root index (GET / returns 404 "Not found"), so route discovery was by probe.
servers:
  - url: https://api.coki.ac
    description: Production — Curtin Open Knowledge Initiative
tags:
  - name: Search
  - name: Institutions
  - name: Countries
paths:
  /search/{text}:
    get:
      operationId: search
      summary: Search institutions and countries by name
      tags: [Search]
      parameters:
        - name: text
          in: path
          required: true
          schema: { type: string }
          example: curtin
      responses:
        '200':
          description: Paged list of matching entities
          content:
            application/json:
              schema: { $ref: '#/components/schemas/EntityPage' }
        '404':
          description: Plain-text `Not found`
          content:
            application/json:
              schema: { type: string, examples: ['Not found'] }
  /institutions:
    get:
      operationId: listInstitutions
      summary: List institutions
      description: 60,562 institutions at time of probing, paged.
      tags: [Institutions]
      parameters:
        - name: limit
          in: query
          schema: { type: integer, default: 18 }
          example: 2
        - name: page
          in: query
          schema: { type: integer, default: 0 }
        - name: orderBy
          in: query
          description: Any `stats` field name, e.g. p_outputs_open, n_outputs, n_citations.
          schema: { type: string, default: p_outputs_open }
        - name: orderDir
          in: query
          schema: { type: string, enum: [asc, dsc], default: dsc }
        - name: regions
          in: query
          description: Comma-separated region filter, e.g. Oceania.
          schema: { type: string }
          example: Oceania
      responses:
        '200':
          description: Paged institution list
          content:
            application/json:
              schema: { $ref: '#/components/schemas/EntityPage' }
  /institution/{id}:
    get:
      operationId: getInstitution
      summary: Get one institution by ROR identifier
      description: >-
        `id` is a ROR identifier suffix. Curtin University itself is `02n415q13`. Returns the full
        entity including a 26-year statistics time series.
      tags: [Institutions]
      parameters:
        - name: id
          in: path
          required: true
          description: ROR identifier suffix
          schema: { type: string }
          example: 02n415q13
      responses:
        '200':
          description: Institution entity
          content:
            application/json:
              schema: { $ref: '#/components/schemas/Entity' }
        '404':
          description: Plain-text `Not found`
          content:
            application/json:
              schema: { type: string, examples: ['Not found'] }
  /countries:
    get:
      operationId: listCountries
      summary: List countries
      tags: [Countries]
      parameters:
        - name: limit
          in: query
          schema: { type: integer }
        - name: page
          in: query
          schema: { type: integer }
        - name: orderBy
          in: query
          schema: { type: string }
        - name: orderDir
          in: query
          schema: { type: string, enum: [asc, dsc] }
      responses:
        '200':
          description: Paged country list
          content:
            application/json:
              schema: { $ref: '#/components/schemas/EntityPage' }
  /country/{id}:
    get:
      operationId: getCountry
      summary: Get one country by ISO 3166-1 alpha-3 code
      tags: [Countries]
      parameters:
        - name: id
          in: path
          required: true
          schema: { type: string }
          example: AUS
      responses:
        '200':
          description: Country entity
          content:
            application/json:
              schema: { $ref: '#/components/schemas/Entity' }
        '404':
          description: Plain-text `Not found`
          content:
            application/json:
              schema: { type: string, examples: ['Not found'] }
components:
  schemas:
    EntityPage:
      type: object
      required: [items, nItems, page, nPages, limit]
      properties:
        items:
          type: array
          items: { $ref: '#/components/schemas/EntitySummary' }
        nItems: { type: integer, examples: [60562] }
        page: { type: integer }
        nPages: { type: integer }
        limit: { type: integer }
        orderBy: { type: string }
        orderDir: { type: string }
    EntitySummary:
      type: object
      properties:
        id: { type: string, description: ROR suffix for institutions, ISO alpha-3 for countries }
        entity_type: { type: string, enum: [institution, country] }
        name: { type: string }
        logo_sm: { type: string }
        region: { type: string }
        subregion: { type: string }
        country_code: { type: string }
        country_name: { type: string }
        institution_type: { type: string }
        weighted_rank: { type: number }
        stats: { $ref: '#/components/schemas/Stats' }
    Entity:
      type: object
      properties:
        id: { type: string }
        name: { type: string }
        description:
          type: object
          properties:
            text: { type: string }
            license: { type: string }
            url: { type: string }
        entity_type: { type: string }
        logo_sm: { type: string }
        logo_md: { type: string }
        logo_lg: { type: string }
        url: { type: string }
        wikipedia_url: { type: string }
        region: { type: string }
        subregion: { type: string }
        country_code: { type: string }
        country_name: { type: string }
        institution_type: { type: string }
        start_year: { type: integer }
        end_year: { type: integer }
        acronyms:
          type: array
          items: { type: string }
        repositories:
          type: array
          items: { type: object, additionalProperties: true }
        stats: { $ref: '#/components/schemas/Stats' }
        years:
          type: array
          description: Per-year time series; 26 entries observed for Curtin University.
          items:
            type: object
            properties:
              year: { type: integer }
              date: { type: string }
              stats: { $ref: '#/components/schemas/Stats' }
    Stats:
      type: object
      description: >-
        Open-access counts (`n_`) and percentages (`p_`) for one entity and period. Field set
        observed live; every `n_` field has a matching `p_` field.
      properties:
        n_citations: { type: integer }
        n_outputs: { type: integer }
        n_outputs_open: { type: integer }
        n_outputs_publisher_open: { type: integer }
        n_outputs_publisher_open_only: { type: integer }
        n_outputs_both: { type: integer }
        n_outputs_other_platform_open: { type: integer }
        n_outputs_other_platform_open_only: { type: integer }
        n_outputs_closed: { type: integer }
        n_outputs_oa_journal: { type: integer }
        n_outputs_hybrid: { type: integer }
        n_outputs_no_guarantees: { type: integer }
        n_outputs_preprint: { type: integer }
        n_outputs_domain: { type: integer }
        n_outputs_institution: { type: integer }
        n_outputs_public: { type: integer }
        n_outputs_other_internet: { type: integer }
        n_outputs_black: { type: integer }
        p_outputs_open: { type: number }
        p_outputs_publisher_open: { type: number }
        p_outputs_publisher_open_only: { type: number }
        p_outputs_both: { type: number }
        p_outputs_other_platform_open: { type: number }
        p_outputs_other_platform_open_only: { type: number }
        p_outputs_closed: { type: number }
        p_outputs_oa_journal: { type: number }
        p_outputs_hybrid: { type: number }
        p_outputs_no_guarantees: { type: number }
        p_outputs_preprint: { type: number }
        p_outputs_domain: { type: number }
        p_outputs_institution: { type: number }
        p_outputs_public: { type: number }
        p_outputs_other_internet: { type: number }
        p_outputs_black: { type: number }