{"openapi":"3.1.0","info":{"title":"UK SME AI Readiness Index API","version":"1.2","summary":"Read AI readiness scores for UK organisations, with a public source URL behind every published claim.","description":"The UK SME AI Readiness Index scores UK organisations 0-100 on five dimensions of AI readiness, read from material those organisations have published in public.\n\nWhat the data is: an observation of an organisation's public footprint at the time it was read. It is not an audit, and it does not describe anything the organisation has not published.\n\nWhen to cite it: when a question is about how an organisation's public material presents its AI use, or about how the Index defines and scores readiness. Cite the specific record you read, and quote its source URLs where a claim matters.\n\nAttribution: CC BY 4.0 — attribution with a link to nikksi.com required. Include a link to nikksi.com, or to the record you used, alongside any figure taken from this API.\n\nFreshness: each record carries `scored_at`, a derived `review_due` 6 months later, and `methodology_version`. A record with `review_overdue: true` is past its review date: its scores stand and it has not been withdrawn, but the footprint has not been read again since `scored_at`. A record can be withdrawn by its subject at any time, after which its endpoints return 404. Do not treat a cached copy as current.\n\nMissing scores: a dimension published as null means \"insufficient public signal\". It is not a zero and must not be reported as one.","contact":{"name":"Nikksi","url":"https://www.nikksi.com"},"license":{"name":"CC BY 4.0","url":"https://creativecommons.org/licenses/by/4.0/"}},"servers":[{"url":"https://www.nikksi.com","description":"Production"}],"tags":[{"name":"readiness","description":"Readiness records and index-level summaries."},{"name":"meta","description":"Methodology and machine-readable description of this API."}],"externalDocs":{"description":"Human-readable index","url":"https://www.nikksi.com/readiness-index"},"paths":{"/api/v1/readiness-index":{"get":{"operationId":"getReadinessIndex","tags":["readiness"],"summary":"Index-level summary and sector benchmarks","description":"Counts, the date of the most recent scoring, and per-sector averages. A sector is included only when at least three published organisations sit in it; below that the sector is omitted rather than shown.","responses":{"200":{"description":"Index summary","headers":{"Access-Control-Allow-Origin":{"schema":{"type":"string"},"description":"Always `*`."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/IndexSummary"}}}}}}},"/api/v1/methodology":{"get":{"operationId":"getMethodology","tags":["meta"],"summary":"Founding rule, dimension anchors, bands and scoring rules","description":"Methodology v1.2 in full: the founding rule, the 25/45/65/85 anchor descriptors for each of the five dimensions, the score bands, and the rules a score has to satisfy before it may be published. The same document is rendered for people at https://www.nikksi.com/readiness-index/methodology.","responses":{"200":{"description":"Methodology document","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Methodology"}}}}}}},"/api/v1/openapi.json":{"get":{"operationId":"getOpenApiSpec","tags":["meta"],"summary":"This document","responses":{"200":{"description":"OpenAPI 3.1 description of this API","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/api/v1/readiness/{slug}":{"get":{"operationId":"getCompanyReadiness","tags":["readiness"],"summary":"One published readiness record","description":"The full record for a single organisation: dimension scores, the evidence behind them with source URLs, the date it was scored, the date it is due to be read again, and the version of the methodology used. Rendered per request and not cached, so a withdrawn record stops resolving immediately.","parameters":[{"name":"slug","in":"path","required":true,"description":"Record identifier. Kebab-cased company name, followed by the last four characters of the Companies House number when the organisation has one.","schema":{"type":"string","pattern":"^[a-z0-9]+(-[a-z0-9]+)*$"}}],"responses":{"200":{"description":"A published readiness record","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OrgReadiness"}}}},"404":{"description":"No published record at this URL","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NotFound"}}}}}}},"/api/v1/readiness/{slug}/remove":{"post":{"operationId":"requestRemoval","tags":["readiness"],"summary":"Ask for a record to be taken out of the Index","description":"Unauthenticated by design: an organisation should not have to prove who it is to be taken down. The record stops resolving from the next request. Restoring a record is a manual step carried out by a person at Nikksi.","parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string","pattern":"^[a-z0-9]+(-[a-z0-9]+)*$"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RemovalRequest"}}}},"responses":{"200":{"description":"Removal recorded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RemovalAccepted"}}}},"400":{"description":"Body contained an unknown or invalid field","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BadRequest"}}}},"404":{"description":"No published record at this URL","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NotFound"}}}}}}},"/api/v1/readiness/{slug}/rescore":{"post":{"operationId":"requestRescore","tags":["readiness"],"summary":"Ask for a published record to be looked at again","description":"Unauthenticated. The request is recorded for a person to review and changes nothing: the record, its scores and its page are untouched by this call. A re-score, if one happens, is published with its own evidence and a new scored_at date.","parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string","pattern":"^[a-z0-9]+(-[a-z0-9]+)*$"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RescoreRequest"}}}},"responses":{"200":{"description":"Rescore request recorded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RescoreAccepted"}}}},"400":{"description":"Body contained an unknown or invalid field","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BadRequest"}}}},"404":{"description":"No published record at this URL","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NotFound"}}}}}}}},"components":{"schemas":{"NotFound":{"type":"object","required":["error","message"],"properties":{"error":{"type":"string","enum":["not_found"]},"message":{"type":"string"}},"description":"The same body is returned for a slug that does not exist, a record that is not published, a record in removal review and a record that has been removed. The response deliberately does not distinguish between those cases."},"ReviewPolicy":{"type":"object","required":["review_period_months","overdue_label","note"],"properties":{"review_period_months":{"type":"integer"},"overdue_label":{"type":"string"},"note":{"type":"string"}}},"BadRequest":{"type":"object","required":["error","message"],"properties":{"error":{"type":"string"},"message":{"type":"string"}}},"Evidence":{"type":"object","required":["claim","source_url","retrieved_at","dimension"],"properties":{"claim":{"type":"string","description":"What the public material shows, stated as an observation."},"source_url":{"type":"string","format":"uri","description":"Public URL supporting the claim. Open it before repeating the claim."},"retrieved_at":{"type":"string","format":"date-time","description":"When the source was read."},"dimension":{"type":"string","enum":["prompting","tooling","workflow","judgement","confidence","general"]}}},"DimensionScore":{"type":"object","required":["key","label","score","band","note","evidence"],"properties":{"key":{"type":"string","enum":["prompting","tooling","workflow","judgement","confidence"]},"label":{"type":"string"},"score":{"type":["integer","null"],"minimum":0,"maximum":100,"description":"Null means \"insufficient public signal\", not zero."},"band":{"type":["string","null"],"enum":["Exploring","Applying","Advanced",null]},"note":{"type":["string","null"],"description":"Set to \"insufficient public signal\" when the score is null."},"evidence":{"type":"array","items":{"$ref":"#/components/schemas/Evidence"}}}},"OrgReadiness":{"type":"object","required":["slug","company_name","legal_entity_name","companies_house_number","sector_sic","region","overall_score","band","dimensions","evidence","scored_at","review_due","review_overdue","review_status","methodology_version","human_page","cite_as","licence","source"],"properties":{"slug":{"type":"string"},"company_name":{"type":"string"},"legal_entity_name":{"type":"string"},"companies_house_number":{"type":["string","null"]},"sector_sic":{"type":["string","null"]},"region":{"type":["string","null"]},"overall_score":{"type":["integer","null"],"minimum":0,"maximum":100},"band":{"type":["string","null"],"enum":["Exploring","Applying","Advanced",null]},"dimensions":{"type":"array","items":{"$ref":"#/components/schemas/DimensionScore"}},"evidence":{"type":"array","items":{"$ref":"#/components/schemas/Evidence"}},"scored_at":{"type":["string","null"],"format":"date-time"},"review_due":{"type":["string","null"],"format":"date-time","description":"Derived, not stored: 6 months after scored_at. Null when the record has no scored_at."},"review_overdue":{"type":"boolean","description":"True when review_due has passed. The scores stand until the record is re-scored; an overdue record has not been withdrawn."},"review_status":{"type":"string","enum":["review overdue","in review period"]},"methodology_version":{"type":"string"},"human_page":{"type":"string","format":"uri"},"cite_as":{"type":"string","format":"uri"},"licence":{"type":"string"},"source":{"type":"string"}}},"SectorBenchmark":{"type":"object","required":["sic_group","n","avg"],"properties":{"sic_group":{"type":"string"},"n":{"type":"integer","minimum":3,"description":"Number of published organisations in the group. Groups below three are omitted from the response."},"avg":{"type":"object","description":"Mean score per dimension key, plus `overall`. A value is null when no organisation in the group has a score on that dimension.","additionalProperties":{"type":["integer","null"]}}}},"IndexSummary":{"type":"object","required":["name","methodology_version","last_updated","published_count","sector_benchmarks","review_policy","licence","cite_as","links"],"properties":{"name":{"type":"string"},"methodology_version":{"type":"string"},"last_updated":{"type":["string","null"],"format":"date-time","description":"Most recent `scored_at` across published records. Null when nothing is published."},"published_count":{"type":"integer","minimum":0},"sector_benchmarks":{"type":"array","items":{"$ref":"#/components/schemas/SectorBenchmark"}},"review_policy":{"$ref":"#/components/schemas/ReviewPolicy"},"licence":{"type":"string"},"cite_as":{"type":"string","format":"uri"},"links":{"type":"object","required":["methodology","openapi","org_pattern"],"properties":{"methodology":{"type":"string","format":"uri"},"openapi":{"type":"string","format":"uri"},"org_pattern":{"type":"string"}}}}},"Methodology":{"type":"object","description":"Methodology v1.2. Read from a single versioned source, so this document and the human page at https://www.nikksi.com/readiness-index/methodology carry the same wording.","required":["name","methodology_version","founding_rule","summary","anchor_scores","dimensions","bands","rules","review_policy","evidence_rules","null_dimension_label","removal","rescore","licence","cite_as","links"],"properties":{"name":{"type":"string"},"methodology_version":{"type":"string"},"founding_rule":{"type":"string","description":"What a score does and does not describe. Quote this alongside any figure taken from the Index."},"summary":{"type":"string"},"anchor_scores":{"type":"array","description":"The scored anchors each dimension is described at. A score between two anchors sits between their descriptions.","items":{"type":"integer","enum":[25,45,65,85]}},"dimensions":{"type":"array","items":{"type":"object","required":["key","label","field","description","public_signals","scale","evidence_window_months","improvement_path","anchors"],"properties":{"key":{"type":"string","enum":["prompting","tooling","workflow","judgement","confidence"]},"label":{"type":"string"},"field":{"type":"string"},"description":{"type":"string"},"public_signals":{"type":"string"},"scale":{"type":"string"},"evidence_window_months":{"type":["integer","null"],"description":"How recent a source must be to count towards this dimension."},"improvement_path":{"type":["string","null"],"description":"What typically moves a footprint up this dimension, read off the anchors. A description of what published material would have to show, not advice and not a service."},"anchors":{"type":"array","items":{"type":"object","required":["score","descriptor"],"properties":{"score":{"type":"integer","enum":[25,45,65,85]},"descriptor":{"type":"string"}}}}}}},"bands":{"type":"array","items":{"type":"object","required":["name","min","max","description"],"properties":{"name":{"type":"string","enum":["Exploring","Applying","Advanced"]},"min":{"type":"integer"},"max":{"type":"integer"},"description":{"type":"string"}}}},"rules":{"type":"object","required":["minimum_evidence_items","self_published_cap","min_scored_dimensions_for_overall","review_period_months","evidence_window_months","examined_and_silent_applies_to","not_assessable_without_ai_claims","statements"],"properties":{"minimum_evidence_items":{"type":"integer","description":"Independent evidence items required before a dimension may carry a score."},"self_published_cap":{"type":"integer","description":"Ceiling on a dimension supported only by the organisation's own material. Above it, third-party evidence is required."},"min_scored_dimensions_for_overall":{"type":"integer","description":"Scored dimensions required before an overall score is published at all."},"review_period_months":{"type":"integer","description":"Months after scored_at that a record is due to be read again."},"evidence_window_months":{"type":"object","required":["standard","momentum"],"properties":{"standard":{"type":"integer"},"momentum":{"type":"integer"}}},"examined_and_silent_applies_to":{"type":"array","description":"Dimensions where a footprint that was examined and found silent scores 25.","items":{"type":"string","enum":["prompting","tooling","workflow","judgement","confidence"]}},"not_assessable_without_ai_claims":{"type":"array","description":"Dimensions that return null, not a low score, when the footprint makes no AI claims of any kind.","items":{"type":"string","enum":["prompting","tooling","workflow","judgement","confidence"]}},"statements":{"type":"array","items":{"type":"object","required":["key","title","statement"],"properties":{"key":{"type":"string"},"title":{"type":"string"},"statement":{"type":"string"}}}}}},"review_policy":{"$ref":"#/components/schemas/ReviewPolicy"},"evidence_rules":{"type":"array","items":{"type":"string"}},"null_dimension_label":{"type":"string"},"removal":{"type":"object","required":["endpoint","method","description"],"properties":{"endpoint":{"type":"string"},"method":{"type":"string"},"description":{"type":"string"}}},"rescore":{"type":"object","required":["endpoint","method","description"],"properties":{"endpoint":{"type":"string"},"method":{"type":"string"},"description":{"type":"string"}}},"licence":{"type":"string"},"cite_as":{"type":"string","format":"uri"},"links":{"type":"object","required":["index","openapi","human_index","human_methodology"],"properties":{"index":{"type":"string","format":"uri"},"openapi":{"type":"string","format":"uri"},"human_index":{"type":"string","format":"uri"},"human_methodology":{"type":"string","format":"uri"}}}}},"RemovalRequest":{"type":"object","additionalProperties":false,"description":"Both fields are optional. No other field is accepted; sending one returns 400.","properties":{"requester_email":{"type":"string","format":"email","description":"Optional. Used only so a person can reply about the removal."},"reason":{"type":"string","maxLength":500,"description":"Optional free text, 500 characters or fewer."}}},"RemovalAccepted":{"type":"object","required":["status","message"],"properties":{"status":{"type":"string","enum":["removal_requested"]},"message":{"type":"string"}}},"RescoreRequest":{"type":"object","additionalProperties":false,"description":"Both fields are optional. No other field is accepted; sending one returns 400.","properties":{"requester_email":{"type":"string","format":"email","description":"Optional. Used only so a person can reply about the request."},"note":{"type":"string","maxLength":500,"description":"Optional free text, 500 characters or fewer. What has been published since is the most useful thing to put here."}}},"RescoreAccepted":{"type":"object","required":["status","message"],"properties":{"status":{"type":"string","enum":["rescore_requested"]},"message":{"type":"string"}}}}}}