Two-component systems, rebuilt for exploration

Interactive API (Swagger)OpenAPI JSONGeneral help

Use the canonical /api/v1 address in scripts. The interactive documentation above is delivered through the website proxy so it remains available even when the deployment does not expose /api/v1directly at the reverse proxy level.

export P2CS_API_BASE_URL="https://www.p2cs.org/api/v1"
curl -fsS "$P2CS_API_BASE_URL/health"

• All identifiers in path segments must be URL encoded. For example, a gene identifier containing # uses %23.
• Paged list responses contain items and pagination. Gene lists return page, page_size, total: null, and has_next to avoid an expensive global count; other lists provide their total when available.
• Use conservative page sizes and iterate over pages. Route-specific limits are declared in Swagger and OpenAPI.
• Optional GFF, FASTA, PFAM, HK/TM, or structure-derived outputs return an availability message or 404 when the source is not present for a record.
• Validation errors use 422; missing records use 404; invalid searchable input may return 400.

curl -sG "$P2CS_API_BASE_URL/genomes" \
  --data-urlencode "query=K-12" \
  --data-urlencode "assembly_level=Complete Genome" \
  --data-urlencode "page=1" \
  --data-urlencode "page_size=25"

curl -L -G "$P2CS_API_BASE_URL/genomes/export" \
  --data-urlencode "query=K-12" \
  --data-urlencode "assembly_level=Complete Genome" \
  --data-urlencode "format=xlsx" \
  -o p2cs_genomes.xlsx

GENE_ID='GCF_000006925%23SF2603'
CLUSTER_ID='RROC_2433902'

curl -sS "$P2CS_API_BASE_URL/genes/$GENE_ID"
curl -sS "$P2CS_API_BASE_URL/genes/$GENE_ID/domain-bioview.svg" -o domains.svg
curl -sG "$P2CS_API_BASE_URL/genes/$GENE_ID/clusters/$CLUSTER_ID/members" \
  --data-urlencode "page=1" \
  --data-urlencode "page_size=50"

INCOMPLETE_HK_ID='GCF_040545925%23ABID56_RS04515'
curl -sS "$P2CS_API_BASE_URL/genes/$INCOMPLETE_HK_ID"

curl -sS -X POST "$P2CS_API_BASE_URL/protein-search" \
  -H "content-type: application/json" \
  --data '{"sequence": ">query\nMKKIAVIGCGNIGLELAKELGADVVVV", "engine": "mmseq2", "target": "RR", "max_results": 25}'

curl -sS -X POST "$P2CS_API_BASE_URL/protein-search/msa" \
  -H "content-type: application/json" \
  --data '{"sequence": ">query\nMKKIAVIGCGNIGLELAKELGADVVVV", "target": "RR", "min_identity_percent": 30, "max_results": 100, "max_sequences": 25}'

curl -sS "$P2CS_API_BASE_URL/ihk/stats"

curl -sG "$P2CS_API_BASE_URL/ihk" \
  --data-urlencode "gene_type=Classic" \
  --data-urlencode "evidence=significant" \
  --data-urlencode "page=1" \
  --data-urlencode "page_size=25"

curl -sS "$P2CS_API_BASE_URL/ihk/IHK_00003806"

• GET/health

  Service health check.

• GET/home/counts

  Current genome, gene, HK, RR, and cluster counts.

• GET/home/summary

  Home-page counts and family distributions.

• GET/genomes

  Search and filter genomes; versioned GCF/GCA accessions are matched to their base accession.

• GET/genomes/taxonomy-tree

  Taxonomy selector for the active genome filters.

• GET/genomes/export

  Complete filtered genome result as TSV or XLSX.

• GET/genomes/metagenomes

  Paged metagenome catalogue.

• GET/genomes/{genome_id}

  Genome metadata and optional quality fields.

• GET/genomes/{genome_id}/gene-stats

  TCS census by class and type.

• GET/genomes/{genome_id}/family-distributions

  HK and RR family distributions.

• GET/genomes/{genome_id}/tcs-organization

  Orphan and grouped TCS organizations.

• GET/genomes/{genome_id}/circular-map

  Genome map payload when local GFF/FNA sources are available.

• GET/genomes/{genome_id}/visual-assets

  Generate or reuse static genome visualization assets.

• GET/genomes/{genome_id}/visual-assets/{asset_name}

  Serve one cached SVG or PNG genome visualization.

• GET/genes

  Search genes by identifier, class, type, family, genome, TCS organization, or HK/RR domains within an organization.

• GET/genes/family-distributions

  Global family distributions.

• GET/genes/{gene_id}

  Full gene record, HK/TM protein features when available, clusters, context, domains, external references, and supplementary HisKA annotation for incomplete HKs.

• GET/genes/{gene_id}/protein-sequence

  Protein sequence and FASTA when a local source is available.

• GET/genes/{gene_id}/domain-bioview.svg

  Domain annotation as SVG.

• GET/genes/{gene_id}/clusters/{cluster_id}/members

  Paged members of a linked cluster.

• GET/genes/{gene_id}/clusters/{cluster_id}/taxonomy-sankey

  Taxonomic Sankey payload for a linked cluster.

• GET/genes/{gene_id}/structure-prediction

  MassiveFold or UniProt structure availability.

• GET/genes/{gene_id}/structure-prediction/file

  Structure file selected with path and optional download parameters.

• GET/genes/{gene_id}/structure-domain-map.svg

  Structure-domain map using the selected renderer.

• GET/genes/{gene_id}/structure-domain-map/file

  Generated SVG or CSV artifact selected with artifact.

• GET/clusters

  Search HKOC, RROC, or IHKOC clusters by identifier, linked gene, representative, kind, run, or identity; HK rows include representative TM features when available.

• GET/clusters/architecture-stats

  HK and RR PFAM architecture statistics.

• GET/clusters/{cluster_id}/pfam-architecture

  Positioned PFAM or IHK HMM architecture for a representative.

• POST/clusters/{cluster_id}/msa

  MMseqs2/MAFFT representative-cluster MSA workflow.

• POST/clusters/{cluster_id}/msa/logo

  Sequence logo for supplied aligned FASTA.

• GET/clusters/{cluster_id}/structure-prediction

  MassiveFold structure availability and files.

• GET/clusters/{cluster_id}/structure-prediction/file

  Structure or workspace file selected with path.

• GET/clusters/{cluster_id}/structure-domain-map.svg

  Generated two-dimensional structure-domain map.

• GET/clusters/{cluster_id}/structure-domain-map/file

  Generated SVG or CSV artifact selected with artifact.

• GET/annexes/external-mappings

  Paged external mappings; scope is p2cs or all.

• POST/protein-search

  MMseqs2, BLASTP, or DIAMOND representative search.

• POST/protein-search/msa

  Search, align selected representatives, and generate an exploratory distance tree.

• GET/ihk/stats

  Counts for incomplete HKs, IHKOC clusters, HMM evidence, and gene types.

• GET/ihk

  Paged search by IHK identifier, gene identifier, type, IHKOC cluster, profile, or evidence.

• GET/ihk/{identifier}

  IHK annotation, sequence, cluster membership, HMM bounds, and representative evidence.

For questions, data issues, or integration requests, contact P2CS Contact at philippe.ortet@cea.fr. Include the full request URL, date, identifier, and returned message. Cite the P2CS-Web resource and record the access date for analyses that use the live catalogue.