{
  "openapi": "3.1.0",
  "info": {
    "title": "Trillion Trees — public read API",
    "version": "1.0.0",
    "summary": "An open, provenance-tracked registry of people creating tree and nature impact.",
    "description": "Read-only. No key, no signup, no rate limit beyond ordinary caching. Every fact carries the source it came from, and the source travels with the fact in the response rather than behind a second request — keeping the provenance attached should be the path of least resistance for anyone building on this.\n\nOnly published records are served. Drafts include private individuals who have not claimed their profile and are never exposed. A record that is withdrawn returns 404 from that moment, which is how a removal request reaches API consumers.",
    "license": {
      "name": "CC BY 4.0",
      "url": "https://creativecommons.org/licenses/by/4.0/"
    }
  },
  "servers": [
    {
      "url": "https://trilliontree.net"
    }
  ],
  "paths": {
    "/api/v1/entities": {
      "get": {
        "summary": "List and search published records",
        "parameters": [
          {
            "name": "q",
            "in": "query",
            "description": "Fuzzy name search.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "kind",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "person",
                "institution",
                "nursery",
                "ngo",
                "company",
                "government_body",
                "location",
                "project"
              ]
            }
          },
          {
            "name": "country",
            "in": "query",
            "description": "ISO 3166-1 alpha-2.",
            "schema": {
              "type": "string",
              "minLength": 2,
              "maxLength": 2
            }
          },
          {
            "name": "admin_area",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100,
              "default": 50
            }
          },
          {
            "name": "offset",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 0,
              "default": 0
            }
          }
        ],
        "responses": {
          "200": {
            "description": "A page of records.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "entities": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "slug": {
                            "type": "string"
                          },
                          "name": {
                            "type": "string"
                          },
                          "kind": {
                            "type": "string"
                          },
                          "country": {
                            "type": [
                              "string",
                              "null"
                            ]
                          },
                          "admin_area": {
                            "type": [
                              "string",
                              "null"
                            ]
                          },
                          "locality": {
                            "type": [
                              "string",
                              "null"
                            ]
                          },
                          "updated_at": {
                            "type": "string",
                            "format": "date-time"
                          },
                          "url": {
                            "type": "string"
                          }
                        }
                      }
                    },
                    "limit": {
                      "type": "integer"
                    },
                    "offset": {
                      "type": "integer"
                    },
                    "license": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "A filter value was not one of the permitted values."
          }
        }
      }
    },
    "/api/v1/entities/{slug}": {
      "get": {
        "summary": "One record, with every live statement and its source",
        "parameters": [
          {
            "name": "slug",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The record.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "slug": {
                      "type": "string"
                    },
                    "name": {
                      "type": "string"
                    },
                    "kind": {
                      "type": "string"
                    },
                    "country": {
                      "type": [
                        "string",
                        "null"
                      ]
                    },
                    "admin_area": {
                      "type": [
                        "string",
                        "null"
                      ]
                    },
                    "locality": {
                      "type": [
                        "string",
                        "null"
                      ]
                    },
                    "published_at": {
                      "type": [
                        "string",
                        "null"
                      ],
                      "format": "date-time"
                    },
                    "updated_at": {
                      "type": "string",
                      "format": "date-time"
                    },
                    "statements": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "required": [
                          "attribute",
                          "confidence",
                          "verified",
                          "source"
                        ],
                        "properties": {
                          "attribute": {
                            "type": "string",
                            "description": "A controlled name from the vocabulary in docs/ATTRIBUTES.md."
                          },
                          "value_text": {
                            "type": [
                              "string",
                              "null"
                            ]
                          },
                          "value_number": {
                            "type": [
                              "number",
                              "null"
                            ]
                          },
                          "value_date": {
                            "type": [
                              "string",
                              "null"
                            ],
                            "format": "date"
                          },
                          "unit": {
                            "type": [
                              "string",
                              "null"
                            ]
                          },
                          "confidence": {
                            "type": "number",
                            "minimum": 0,
                            "maximum": 1
                          },
                          "verified": {
                            "type": "boolean",
                            "description": "confidence >= 0.7. Below this the website labels the fact \"reported, not verified\"; anything republishing it should do the same."
                          },
                          "source": {
                            "type": "object",
                            "description": "Where the fact came from. Present on every statement, without exception.",
                            "required": [
                              "kind",
                              "retrieved_at"
                            ],
                            "properties": {
                              "kind": {
                                "type": "string",
                                "enum": [
                                  "url",
                                  "whatsapp",
                                  "phone",
                                  "email",
                                  "document",
                                  "partner_feed",
                                  "owner_submitted",
                                  "field_visit"
                                ]
                              },
                              "url": {
                                "type": [
                                  "string",
                                  "null"
                                ],
                                "format": "uri"
                              },
                              "title": {
                                "type": [
                                  "string",
                                  "null"
                                ]
                              },
                              "publisher": {
                                "type": [
                                  "string",
                                  "null"
                                ]
                              },
                              "retrieved_at": {
                                "type": "string",
                                "format": "date-time"
                              }
                            }
                          }
                        }
                      }
                    },
                    "license": {
                      "type": "string"
                    },
                    "attribution": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "No such record, or it is not published — draft, in review, or withdrawn. 404 rather than 403, because 403 would confirm the record exists."
          }
        }
      }
    }
  }
}