API-Spezifikationsinhalt ist auf Englisch

Endpunktnamen, Pfade, Feldnamen und Beschreibungen stammen aus der OpenAPI-Spezifikation und bleiben sprachübergreifend auf Englisch.

REST-API-Referenz

Version 0.1.0

Basis-URL: https://bdp.dev

Alle versionierten Endpunkte befinden sich unter /api/v1. Antworten sind eingebettet: { success, data, meta? }

System

Liveness/readiness probe and platform-wide statistics.

get/api/stats

Return aggregate platform statistics (data source count, org count, download count). Results are computed on demand from the live database.

Antworten

200Current platform statistics.StatsResponse

{
  "datasources": 23,
  "downloads": 18742,
  "organizations": 4
}

500Database query failed.ErrorResponse

Beispielanfrage

curl -X GET 'https://bdp.dev/api/stats' \
  -H 'Accept: application/json'

get/health

Check whether the server and its database connection are healthy. Suitable for use as a liveness / readiness probe.

Antworten

200Server and database are healthy.HealthResponse

{
  "database": "connected",
  "status": "healthy"
}

503Database is unreachable. Retry after a short delay.

Beispielanfrage

curl -X GET 'https://bdp.dev/health' \
  -H 'Accept: application/json'

Organizations

Publisher organizations that namespace data sources. Every data source is owned by exactly one organization, identified by `{org_slug}/{data_source_slug}`.

get/api/v1/organizations

Return a paginated list of all organizations sorted by creation date (newest first). Filter by `name` (substring, case-insensitive) or by the `is_system` flag.

Parameter

Name	In	Typ	Beschreibung
`page`	query	int64	Page number, 1-based. Default: `1`.
`per_page`	query	int64	Items per page. Default: `20`. Maximum: `100`.
`name`	query	string	Case-insensitive substring filter on the organization name.
`is_system`	query	boolean	When `true`, return only internal BDP system organizations. When `false`, exclude them. Omit to return all.

Antworten

200Paginated list of organizations.OrganizationListResponse

{
  "data": [
    null
  ],
  "meta": null,
  "success": true
}

400Invalid pagination parameters.ErrorResponse

500Internal server error.ErrorResponse

Beispielanfrage

curl -X GET 'https://bdp.dev/api/v1/organizations' \
  -H 'Accept: application/json'

post/api/v1/organizations

Register a new publisher organization. The `slug` is permanent — it cannot be changed after creation. Choose something stable that can safely appear in download URLs and citation text.

Anfrage-BodyCreateOrganizationRequest

Organization details. The `slug` must be globally unique.

{
  "description": "Computational biology group at Example University.",
  "homepage_url": "https://mylab.example.edu",
  "name": "My Research Lab",
  "slug": "my-lab"
}

Antworten

201Organization created successfully.OrganizationResponse

{
  "data": {
    "created_at": "2024-01-15T10:30:00Z",
    "description": "Genome databases for vertebrates and other eukaryotic species.",
    "homepage_url": "https://www.ensembl.org",
    "id": "018e4a2b-c3d1-7e4f-a5b6-1234567890ab",
    "is_system": false,
    "name": "Ensembl",
    "slug": "ensembl",
    "updated_at": "2024-03-20T14:22:00Z"
  },
  "success": true
}

400Slug or name failed validation.ErrorResponse

409An organization with that slug already exists.ErrorResponse

500Internal server error.ErrorResponse

Beispielanfrage

curl -X POST 'https://bdp.dev/api/v1/organizations' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
  "description": "Computational biology group at Example University.",
  "homepage_url": "https://mylab.example.edu",
  "name": "My Research Lab",
  "slug": "my-lab"
}'

get/api/v1/organizations/{slug}

Retrieve a single organization by its slug.

Parameter

Name	In	Typ	Beschreibung
`slug`*	path	string	Organization slug (e.g. `ensembl`).

Antworten

200Organization found.OrganizationResponse

{
  "data": {
    "created_at": "2024-01-15T10:30:00Z",
    "description": "Genome databases for vertebrates and other eukaryotic species.",
    "homepage_url": "https://www.ensembl.org",
    "id": "018e4a2b-c3d1-7e4f-a5b6-1234567890ab",
    "is_system": false,
    "name": "Ensembl",
    "slug": "ensembl",
    "updated_at": "2024-03-20T14:22:00Z"
  },
  "success": true
}

404No organization with that slug exists.ErrorResponse

500Internal server error.ErrorResponse

Beispielanfrage

curl -X GET 'https://bdp.dev/api/v1/organizations/slug' \
  -H 'Accept: application/json'

put/api/v1/organizations/{slug}

Update mutable fields of an existing organization (`name`, `description`, `homepage_url`). The `slug` and `is_system` flag cannot be changed. Supply only the fields you want to modify.

Parameter

Name	In	Typ	Beschreibung
`slug`*	path	string	Slug of the organization to update.

Anfrage-BodyUpdateOrganizationRequest

Fields to update. Omitted fields are left unchanged.

{
  "description": "Updated description.",
  "name": "My Research Lab (Renamed)"
}

Antworten

200Organization updated.OrganizationResponse

{
  "data": {
    "created_at": "2024-01-15T10:30:00Z",
    "description": "Genome databases for vertebrates and other eukaryotic species.",
    "homepage_url": "https://www.ensembl.org",
    "id": "018e4a2b-c3d1-7e4f-a5b6-1234567890ab",
    "is_system": false,
    "name": "Ensembl",
    "slug": "ensembl",
    "updated_at": "2024-03-20T14:22:00Z"
  },
  "success": true
}

400Validation error.ErrorResponse

404Organization not found.ErrorResponse

500Internal server error.ErrorResponse

Beispielanfrage

curl -X PUT 'https://bdp.dev/api/v1/organizations/slug' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
  "description": "Updated description.",
  "name": "My Research Lab (Renamed)"
}'

delete/api/v1/organizations/{slug}

Permanently delete an organization. **Fails with `409 Conflict`** if the organization still owns any data sources. Delete or transfer all data sources before deleting the org.

Parameter

Name	In	Typ	Beschreibung
`slug`*	path	string	Slug of the organization to delete.

Antworten

200Organization deleted. Returns the deleted record.OrganizationResponse

{
  "data": {
    "created_at": "2024-01-15T10:30:00Z",
    "description": "Genome databases for vertebrates and other eukaryotic species.",
    "homepage_url": "https://www.ensembl.org",
    "id": "018e4a2b-c3d1-7e4f-a5b6-1234567890ab",
    "is_system": false,
    "name": "Ensembl",
    "slug": "ensembl",
    "updated_at": "2024-03-20T14:22:00Z"
  },
  "success": true
}

404Organization not found.ErrorResponse

409Organization still has associated data sources.ErrorResponse

500Internal server error.ErrorResponse

Beispielanfrage

curl -X DELETE 'https://bdp.dev/api/v1/organizations/slug' \
  -H 'Accept: application/json'

Data Sources

The core registry primitive. A data source represents a named, versioned dataset from a specific upstream database (UniProt, Ensembl, PubMed, …). Versions are immutable once published.

get/api/v1/data-sources

Return a paginated list of data sources. Results are sorted newest-first. Combine filters to narrow results: `organization_id` + `source_type` is a common pattern (e.g. all UniProt sources for a specific org).

Parameter

Name	In	Typ	Beschreibung
`page`	query	int64	Page number (1-based, default `1`).
`per_page`	query	int64	Items per page (default `20`, max `100`).
`organization_id`	query	string	Filter by organization UUID. Use alongside `GET /api/v1/organizations` to resolve a slug to its UUID.
`source_type`	query	string	Filter by canonical source type (e.g. `uniprot`). See `GET /api/v1/data-sources/source-types` for valid values.
`organism_id`	query	string	Filter by organism UUID.

Antworten

200Paginated list of data sources.DataSourceListResponse

{
  "data": [
    null
  ],
  "meta": null,
  "success": true
}

400Invalid pagination parameters.ErrorResponse

500Internal server error.ErrorResponse

Beispielanfrage

curl -X GET 'https://bdp.dev/api/v1/data-sources' \
  -H 'Accept: application/json'

post/api/v1/data-sources

Anfrage-BodyCreateDataSourceRequest

Data source metadata. The `slug` must be unique within the organization.

{
  "description": "Complete reviewed UniProt proteome for Homo sapiens.",
  "external_id": "UP000005640",
  "name": "Homo sapiens Proteome",
  "organization_id": "018e4a2b-c3d1-7e4f-a5b6-1234567890ab",
  "slug": "homo-sapiens-proteome",
  "source_type": "uniprot"
}

Antworten

201Data source created.DataSourceResponse

{
  "data": {
    "created_at": "2024-01-20T08:00:00Z",
    "description": "Complete reviewed UniProt proteome for Homo sapiens (UP000005640).",
    "download_count": 347,
    "external_id": "UP000005640",
    "id": "018e4a2b-0001-7e4f-a5b6-1234567890ab",
    "name": "Homo sapiens Proteome",
    "organism_id": null,
    "organization_id": "018e4a2b-c3d1-7e4f-a5b6-1234567890ab",
    "slug": "homo-sapiens-proteome",
    "source_type": "uniprot",
    "updated_at": "2024-03-01T12:00:00Z"
  },
  "success": true
}

400Validation error (slug, name, or source_type).ErrorResponse

404Referenced organization or organism not found.ErrorResponse

409A data source with that slug already exists in the organization.ErrorResponse

500Internal server error.ErrorResponse

Beispielanfrage

curl -X POST 'https://bdp.dev/api/v1/data-sources' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
  "description": "Complete reviewed UniProt proteome for Homo sapiens.",
  "external_id": "UP000005640",
  "name": "Homo sapiens Proteome",
  "organization_id": "018e4a2b-c3d1-7e4f-a5b6-1234567890ab",
  "slug": "homo-sapiens-proteome",
  "source_type": "uniprot"
}'

get/api/v1/data-sources/source-types

Return the sorted list of all distinct `source_type` values currently present in the registry. Use the values returned here as the `source_type` filter in `GET /api/v1/data-sources` and `GET /api/v1/search`.

Antworten

200Sorted list of canonical source-type identifiers.SourceTypesResponse

{
  "data": [
    "chebi",
    "clinvar",
    "ensembl",
    "genbank",
    "gene_ontology",
    "hpo",
    "interpro",
    "mondo",
    "ncbi_taxonomy",
    "pubmed",
    "reactome",
    "uniprot"
  ],
  "success": true
}

500Internal server error.ErrorResponse

Beispielanfrage

curl -X GET 'https://bdp.dev/api/v1/data-sources/source-types' \
  -H 'Accept: application/json'

get/api/v1/data-sources/{org}/{slug}

Retrieve full details for a single data source, including its published versions.

Parameter

Name	In	Typ	Beschreibung
`org`*	path	string	Organization slug.
`slug`*	path	string	Data source slug.

Antworten

200Data source details.DataSourceResponse

{
  "data": {
    "created_at": "2024-01-20T08:00:00Z",
    "description": "Complete reviewed UniProt proteome for Homo sapiens (UP000005640).",
    "download_count": 347,
    "external_id": "UP000005640",
    "id": "018e4a2b-0001-7e4f-a5b6-1234567890ab",
    "name": "Homo sapiens Proteome",
    "organism_id": null,
    "organization_id": "018e4a2b-c3d1-7e4f-a5b6-1234567890ab",
    "slug": "homo-sapiens-proteome",
    "source_type": "uniprot",
    "updated_at": "2024-03-01T12:00:00Z"
  },
  "success": true
}

404Organization or data source not found.ErrorResponse

500Internal server error.ErrorResponse

Beispielanfrage

curl -X GET 'https://bdp.dev/api/v1/data-sources/org/slug' \
  -H 'Accept: application/json'

put/api/v1/data-sources/{org}/{slug}

Update mutable metadata for a data source. The `slug` and `source_type` are immutable; published versions are unaffected.

Parameter

Name	In	Typ	Beschreibung
`org`*	path	string	Organization slug.
`slug`*	path	string	Data source UUID or slug.

Anfrage-BodyUpdateDataSourceRequest

Fields to update. Omit fields that should remain unchanged.

{
  "name": "Homo sapiens Proteome (reviewed)"
}

Antworten

200Data source updated.DataSourceResponse

{
  "data": {
    "created_at": "2024-01-20T08:00:00Z",
    "description": "Complete reviewed UniProt proteome for Homo sapiens (UP000005640).",
    "download_count": 347,
    "external_id": "UP000005640",
    "id": "018e4a2b-0001-7e4f-a5b6-1234567890ab",
    "name": "Homo sapiens Proteome",
    "organism_id": null,
    "organization_id": "018e4a2b-c3d1-7e4f-a5b6-1234567890ab",
    "slug": "homo-sapiens-proteome",
    "source_type": "uniprot",
    "updated_at": "2024-03-01T12:00:00Z"
  },
  "success": true
}

400Validation error.ErrorResponse

404Data source not found.ErrorResponse

500Internal server error.ErrorResponse

Beispielanfrage

curl -X PUT 'https://bdp.dev/api/v1/data-sources/org/slug' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
  "name": "Homo sapiens Proteome (reviewed)"
}'

delete/api/v1/data-sources/{org}/{slug}

Permanently delete a data source. **Fails with `409 Conflict`** when the data source has one or more published versions. Versions are immutable; delete the data source only when it is truly being retired.

Parameter

Name	In	Typ	Beschreibung
`org`*	path	string	Organization slug.
`slug`*	path	string	Data source UUID or slug.

Antworten

200Data source deleted. Returns the deleted record.DataSourceResponse

{
  "data": {
    "created_at": "2024-01-20T08:00:00Z",
    "description": "Complete reviewed UniProt proteome for Homo sapiens (UP000005640).",
    "download_count": 347,
    "external_id": "UP000005640",
    "id": "018e4a2b-0001-7e4f-a5b6-1234567890ab",
    "name": "Homo sapiens Proteome",
    "organism_id": null,
    "organization_id": "018e4a2b-c3d1-7e4f-a5b6-1234567890ab",
    "slug": "homo-sapiens-proteome",
    "source_type": "uniprot",
    "updated_at": "2024-03-01T12:00:00Z"
  },
  "success": true
}

404Data source not found.ErrorResponse

409Data source has published versions and cannot be deleted.ErrorResponse

500Internal server error.ErrorResponse

Beispielanfrage

curl -X DELETE 'https://bdp.dev/api/v1/data-sources/org/slug' \
  -H 'Accept: application/json'

post/api/v1/data-sources/{org}/{slug}/versions

Publish a new immutable version for an existing data source. Versions cannot be modified or deleted after publication. If you need to re-release the same upstream release, increment a patch suffix (e.g. `2024-03-r2`).

Parameter

Name	In	Typ	Beschreibung
`org`*	path	string	Organization slug.
`slug`*	path	string	Data source slug.

Anfrage-BodyPublishVersionRequest

Version metadata. The `version` string must be unique for this data source.

{
  "checksum": "sha256:a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8",
  "data_source_id": "018e4a2b-0001-7e4f-a5b6-1234567890ab",
  "download_url": "https://storage.bdp.dev/ensembl/homo-sapiens-proteome/2024-03.tar.gz",
  "file_count": 3,
  "size_bytes": 2340000000,
  "version": "2024-03"
}

Antworten

201Version published.DataSourceVersionResponse

{
  "data": {
    "checksum": "sha256:a3b4c5d6...",
    "data_source_id": "018e4a2b-0001-7e4f-a5b6-1234567890ab",
    "file_count": 3,
    "id": "018e4a2b-0002-7e4f-a5b6-1234567890ab",
    "published_at": "2024-03-05T09:00:00Z",
    "size_bytes": 2340000000,
    "version": "2024-03",
    "version_string": "March 2024"
  },
  "success": true
}

400Validation error (version string, size, etc.).ErrorResponse

404Data source not found.ErrorResponse

409A version with that identifier already exists.ErrorResponse

500Internal server error.ErrorResponse

Beispielanfrage

curl -X POST 'https://bdp.dev/api/v1/data-sources/org/slug/versions' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
  "checksum": "sha256:a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8",
  "data_source_id": "018e4a2b-0001-7e4f-a5b6-1234567890ab",
  "download_url": "https://storage.bdp.dev/ensembl/homo-sapiens-proteome/2024-03.tar.gz",
  "file_count": 3,
  "size_bytes": 2340000000,
  "version": "2024-03"
}'

get/api/v1/data-sources/{org}/{slug}/{version}

Retrieve metadata for a specific published version.

Parameter

Name	In	Typ	Beschreibung
`org`*	path	string	Organization slug.
`slug`*	path	string	Data source slug.
`version`*	path	string	Version string exactly as published (e.g. `2024-03`, `1.0.0`).

Antworten

200Version metadata.DataSourceVersionResponse

{
  "data": {
    "checksum": "sha256:a3b4c5d6...",
    "data_source_id": "018e4a2b-0001-7e4f-a5b6-1234567890ab",
    "file_count": 3,
    "id": "018e4a2b-0002-7e4f-a5b6-1234567890ab",
    "published_at": "2024-03-05T09:00:00Z",
    "size_bytes": 2340000000,
    "version": "2024-03",
    "version_string": "March 2024"
  },
  "success": true
}

404Organization, data source, or version not found.ErrorResponse

500Internal server error.ErrorResponse

Beispielanfrage

curl -X GET 'https://bdp.dev/api/v1/data-sources/org/slug/version' \
  -H 'Accept: application/json'

get/api/v1/data-sources/{org}/{slug}/{version}/dependencies

List all declared dependencies for a specific version. Dependencies express cross-version relationships (e.g. a GenBank release requires a particular NCBI Taxonomy snapshot). The BDP CLI uses this endpoint to resolve the full dependency graph before downloading.

Parameter

Name	In	Typ	Beschreibung
`org`*	path	string	Organization slug.
`slug`*	path	string	Data source slug.
`version`*	path	string	Version string.
`page`	query	int64	Page number (default `1`).
`per_page`	query	int64	Items per page (default `20`, max `100`).

Antworten

200Paginated list of dependencies.DependencyListResponse

{
  "data": [
    null
  ],
  "meta": null,
  "success": true
}

404Organization, data source, or version not found.ErrorResponse

500Internal server error.ErrorResponse

Beispielanfrage

curl -X GET 'https://bdp.dev/api/v1/data-sources/org/slug/version/dependencies' \
  -H 'Accept: application/json'

Search

Full-text search (`GET /search`) and trigram autocomplete (`GET /search/suggestions`) across organizations and data sources.

get/api/v1/search

Full-text search across organizations and data sources. Powered by PostgreSQL `plainto_tsquery` over a materialized search index. Results are ranked by `ts_rank` and optionally filtered by type or source type. **Tip:** for real-time type-ahead use `GET /api/v1/search/suggestions` instead — it uses trigram similarity and is optimized for single-keystroke latency.

Parameter

Name	In	Typ	Beschreibung
`query`*	query	string	Search query. Supports multi-word natural language queries (e.g. `homo sapiens proteome`).
`type_filter`	query	string	Restrict results to one result type: `organization`, `data_source`, or `tool`. Omit to search all types.
`source_type`	query	string	Restrict to data sources of a specific type (e.g. `uniprot`). Only effective when `type_filter=data_source`.
`page`	query	int64	Page number (default `1`).
`per_page`	query	int64	Items per page (default `20`, max `100`).

Antworten

200Ranked search results.SearchResultsResponse

{
  "data": [
    null
  ],
  "meta": null,
  "success": true
}

400`query` parameter is missing or empty.ErrorResponse

500Internal server error.ErrorResponse

Beispielanfrage

curl -X GET 'https://bdp.dev/api/v1/search' \
  -H 'Accept: application/json'

get/api/v1/search/suggestions

Return autocomplete suggestions for a partial query string. Uses PostgreSQL trigram similarity (`pg_trgm`) for sub-100 ms latency. Designed for client-side type-ahead components — call on every keystroke once the input is ≥ 2 characters.

Parameter

Name	In	Typ	Beschreibung
`q`*	query	string	Partial query string. Must be at least 2 characters.
`limit`	query	int64	Maximum number of suggestions to return. Default `10`, max `25`.

Antworten

200Autocomplete suggestions.SuggestionsResponse

{
  "data": [
    null
  ],
  "success": true
}

400Query is too short (< 2 characters).ErrorResponse

500Internal server error.ErrorResponse

Beispielanfrage

curl -X GET 'https://bdp.dev/api/v1/search/suggestions' \
  -H 'Accept: application/json'

Pipeline Runs

Read-only observability for the server-side ingestion pipelines. Use `GET /pipeline-runs/latest` to check whether all upstream databases have been ingested recently.

get/api/v1/pipeline-runs

List pipeline run history, most recent first. Use this endpoint to audit when a specific pipeline last ran, how long it took, and whether any runs failed. For a quick freshness overview use `GET /api/v1/pipeline-runs/latest` instead.

Parameter

Name	In	Typ	Beschreibung
`pipeline_name`	query	string	Filter by pipeline name (e.g. `uniprot`, `ensembl`).
`status`	query	string	Filter by run status: `pending`, `running`, `completed`, or `failed`.
`page`	query	int64	Page number (default `1`).
`per_page`	query	int64	Items per page (default `20`, max `100`).

Antworten

200Paginated list of pipeline run records.PipelineRunListResponse

{
  "data": [
    null
  ],
  "meta": null,
  "success": true
}

500Internal server error.ErrorResponse

Beispielanfrage

curl -X GET 'https://bdp.dev/api/v1/pipeline-runs' \
  -H 'Accept: application/json'

get/api/v1/pipeline-runs/latest

Return the single most-recent run record for every pipeline. A quick way to assess the health of the ingestion system as a whole. The response is a map keyed by `pipeline_name`, so a missing key means that pipeline has never been run on this instance.

Antworten

200Latest run per pipeline, keyed by pipeline name.PipelineRunLatestResponse

{
  "data": null,
  "success": true
}

500Internal server error.ErrorResponse

Beispielanfrage

curl -X GET 'https://bdp.dev/api/v1/pipeline-runs/latest' \
  -H 'Accept: application/json'

Dokumentation

REST-API-Referenz

System

Organizations

Data Sources

Search

Pipeline Runs