{
  "openapi": "3.1.0",
  "info": {
    "title": "Stockonomy figure check",
    "version": "1.0.0",
    "description": "Compares a stated figure with the SEC filing it came from. A verdict read from a filing names its accession. A verdict is a comparison with a filing and makes no statement that a number is correct or sound. The API host is the one this site's pages call; it is shown in the examples on /developers."
  },
  "paths": {
    "/v1/resolve": {
      "post": {
        "operationId": "resolve",
        "summary": "Check up to 20 claims about one ticker; writes a receipt on the key owner's hash chain",
        "security": [
          {
            "ApiKey": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "ticker",
                  "claims"
                ],
                "properties": {
                  "ticker": {
                    "type": "string",
                    "examples": [
                      "AAPL"
                    ]
                  },
                  "claims": {
                    "type": "array",
                    "minItems": 1,
                    "maxItems": 20,
                    "items": {
                      "oneOf": [
                        {
                          "type": "object",
                          "required": [
                            "type",
                            "concept",
                            "value"
                          ],
                          "properties": {
                            "type": {
                              "const": "figure"
                            },
                            "concept": {
                              "type": "string",
                              "description": "One of the line items, or segment_revenue with member. Others are answered refused.",
                              "examples": [
                                "buybacks",
                                "capex",
                                "cost_of_revenue"
                              ]
                            },
                            "value": {
                              "type": "number",
                              "description": "US dollars (shares for diluted_shares), at most 1e15"
                            },
                            "fiscal_year": {
                              "type": "integer",
                              "minimum": 1990,
                              "maximum": 2100
                            },
                            "period": {
                              "enum": [
                                "year",
                                "quarter",
                                "six_months",
                                "nine_months"
                              ]
                            },
                            "period_end": {
                              "type": "string",
                              "format": "date"
                            },
                            "rounded_to": {
                              "type": "number",
                              "minimum": 1,
                              "maximum": 1000000000000.0
                            },
                            "member": {
                              "type": "string"
                            },
                            "as_of": {
                              "type": "string",
                              "format": "date"
                            }
                          },
                          "additionalProperties": true
                        },
                        {
                          "type": "object",
                          "required": [
                            "type",
                            "concept",
                            "fiscal_year",
                            "value"
                          ],
                          "properties": {
                            "type": {
                              "enum": [
                                "growth",
                                "margin"
                              ]
                            },
                            "concept": {
                              "type": "string",
                              "description": "Growth takes any listed line item. Margin takes a dollar flow other than revenue. Neither takes segment_revenue, a member or a period; both name fiscal_year."
                            },
                            "fiscal_year": {
                              "type": "integer",
                              "minimum": 1990,
                              "maximum": 2100
                            },
                            "value": {
                              "type": "number",
                              "description": "A percentage"
                            },
                            "period_end": {
                              "type": "string",
                              "format": "date"
                            },
                            "prior_period_end": {
                              "type": "string",
                              "format": "date"
                            },
                            "as_of": {
                              "type": "string",
                              "format": "date"
                            }
                          },
                          "additionalProperties": true
                        },
                        {
                          "type": "object",
                          "required": [
                            "type",
                            "since_year"
                          ],
                          "properties": {
                            "type": {
                              "enum": [
                                "no_restatement",
                                "no_auditor_change",
                                "no_bankruptcy",
                                "no_delisting_notice",
                                "no_late_filing"
                              ]
                            },
                            "since_year": {
                              "type": "integer",
                              "minimum": 1990,
                              "maximum": 2100,
                              "description": "Events are read for the last 7 calendar years only; an earlier since_year is answered refused."
                            },
                            "as_of": {
                              "type": "string",
                              "format": "date"
                            }
                          },
                          "additionalProperties": true
                        }
                      ]
                    }
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "A receipt and one verdict per claim, in order",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "receipt": {
                      "type": "object",
                      "additionalProperties": true
                    },
                    "verdicts": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "verdict": {
                            "enum": [
                              "matches_filing",
                              "first_filed_differently",
                              "contradicted",
                              "not_on_file",
                              "refused",
                              "absent_in_read"
                            ]
                          },
                          "statement": {
                            "type": "string",
                            "description": "Names the filing the verdict was read from"
                          },
                          "accession": {
                            "type": [
                              "string",
                              "null"
                            ]
                          }
                        },
                        "required": [
                          "verdict"
                        ],
                        "additionalProperties": true
                      }
                    }
                  },
                  "additionalProperties": true
                }
              }
            }
          },
          "401": {
            "description": "Missing, malformed, unknown or revoked key",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "detail": {}
                  },
                  "additionalProperties": true
                }
              }
            }
          },
          "422": {
            "description": "The body failed validation; detail says why",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "detail": {}
                  },
                  "additionalProperties": true
                }
              }
            }
          },
          "429": {
            "description": "An allowance ran out; Retry-After says when",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "detail": {}
                  },
                  "additionalProperties": true
                }
              }
            }
          },
          "502": {
            "description": "An upstream read failed",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "detail": {}
                  },
                  "additionalProperties": true
                }
              }
            }
          },
          "503": {
            "description": "A source or the key store is unavailable; no receipt was written",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "detail": {}
                  },
                  "additionalProperties": true
                }
              }
            }
          }
        }
      }
    },
    "/check/public": {
      "get": {
        "operationId": "publicCheck",
        "summary": "Free, logged-out check of one figure; writes no receipt",
        "security": [],
        "parameters": [
          {
            "name": "ticker",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "concept",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "value",
            "in": "query",
            "required": true,
            "schema": {
              "type": "number"
            }
          },
          {
            "name": "fiscal_year",
            "in": "query",
            "schema": {
              "type": "integer"
            }
          },
          {
            "name": "period_end",
            "in": "query",
            "schema": {
              "type": "string",
              "format": "date"
            }
          },
          {
            "name": "period",
            "in": "query",
            "schema": {
              "enum": [
                "year",
                "quarter",
                "six_months",
                "nine_months"
              ]
            }
          },
          {
            "name": "rounded_to",
            "in": "query",
            "schema": {
              "type": "number"
            }
          },
          {
            "name": "member",
            "in": "query",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "One verdict, the accessions read, and a reproducibility id",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "id": {
                      "type": "string"
                    },
                    "ticker": {
                      "type": "string"
                    },
                    "engine_version": {
                      "type": "string"
                    },
                    "as_of": {
                      "type": "string",
                      "format": "date"
                    },
                    "accessions": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      }
                    },
                    "verdicts": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "verdict": {
                            "enum": [
                              "matches_filing",
                              "first_filed_differently",
                              "contradicted",
                              "not_on_file",
                              "refused",
                              "absent_in_read"
                            ]
                          },
                          "statement": {
                            "type": "string",
                            "description": "Names the filing the verdict was read from"
                          },
                          "accession": {
                            "type": [
                              "string",
                              "null"
                            ]
                          }
                        },
                        "required": [
                          "verdict"
                        ],
                        "additionalProperties": true
                      }
                    }
                  },
                  "additionalProperties": true
                }
              }
            }
          },
          "422": {
            "description": "The claim failed validation",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "detail": {}
                  },
                  "additionalProperties": true
                }
              }
            }
          },
          "429": {
            "description": "This address used its free checks, or is calling faster than the per-minute and per-day limits.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "detail": {}
                  },
                  "additionalProperties": true
                }
              }
            }
          },
          "502": {
            "description": "An upstream read failed",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "detail": {}
                  },
                  "additionalProperties": true
                }
              }
            }
          },
          "503": {
            "description": "A source is unavailable",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "detail": {}
                  },
                  "additionalProperties": true
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "ApiKey": {
        "type": "apiKey",
        "in": "header",
        "name": "X-Api-Key",
        "description": "Made in Settings, API keys. Format sk_live_ plus 64 hex."
      }
    }
  }
}