init
This commit is contained in:
+207
@@ -0,0 +1,207 @@
|
||||
openapi: 3.1.0
|
||||
info:
|
||||
title: AI Usage Disclosure API
|
||||
version: 1.6.1
|
||||
description: Stateless multilingual badge, declaration and validation API with optional licensed presentation capabilities.
|
||||
servers:
|
||||
- url: https://ai.example.org
|
||||
paths:
|
||||
/badge/{preset}.svg:
|
||||
get:
|
||||
summary: Render a standard preset badge
|
||||
parameters:
|
||||
- name: preset
|
||||
in: path
|
||||
required: true
|
||||
schema: {type: string, enum: [no-ai, research, summary, full]}
|
||||
- {$ref: '#/components/parameters/language'}
|
||||
- {$ref: '#/components/parameters/theme'}
|
||||
- {$ref: '#/components/parameters/style'}
|
||||
- {name: link, in: query, schema: {type: string, description: Use auto to link to the generated declaration page.}}
|
||||
responses:
|
||||
"200":
|
||||
description: SVG badge
|
||||
content:
|
||||
image/svg+xml: {schema: {type: string}}
|
||||
/v1/badge.svg:
|
||||
get:
|
||||
summary: Render an SVG badge from structured parameters
|
||||
description: Custom labels and colours require the custom_badge capability.
|
||||
parameters:
|
||||
- {$ref: '#/components/parameters/extent'}
|
||||
- {$ref: '#/components/parameters/language'}
|
||||
- {name: preset, in: query, schema: {type: string, enum: [no-ai, research, summary, full]}}
|
||||
- {$ref: '#/components/parameters/theme'}
|
||||
- {$ref: '#/components/parameters/style'}
|
||||
- {name: link, in: query, schema: {type: string}}
|
||||
- {name: badgeLabel, in: query, description: Licensed feature custom_badge, schema: {type: string, maxLength: 40}}
|
||||
- {name: badgeMessage, in: query, description: Licensed feature custom_badge, schema: {type: string, maxLength: 80}}
|
||||
- {name: leftColor, in: query, description: Licensed feature custom_badge, schema: {type: string, pattern: '^#[0-9A-Fa-f]{6}$'}}
|
||||
- {name: rightColor, in: query, description: Licensed feature custom_badge, schema: {type: string, pattern: '^#[0-9A-Fa-f]{6}$'}}
|
||||
responses:
|
||||
"200":
|
||||
description: SVG badge
|
||||
content:
|
||||
image/svg+xml: {schema: {type: string}}
|
||||
"403": {$ref: '#/components/responses/ProRequired'}
|
||||
/declaration:
|
||||
get:
|
||||
summary: Render a human-readable declaration page
|
||||
parameters:
|
||||
- {$ref: '#/components/parameters/preset'}
|
||||
- {$ref: '#/components/parameters/extent'}
|
||||
- {$ref: '#/components/parameters/language'}
|
||||
- {$ref: '#/components/parameters/component'}
|
||||
- {$ref: '#/components/parameters/activities'}
|
||||
- {$ref: '#/components/parameters/review'}
|
||||
- {$ref: '#/components/parameters/assurance'}
|
||||
- {$ref: '#/components/parameters/customTitle'}
|
||||
- {$ref: '#/components/parameters/customDescription'}
|
||||
- {$ref: '#/components/parameters/badgeLabel'}
|
||||
- {$ref: '#/components/parameters/badgeMessage'}
|
||||
- {$ref: '#/components/parameters/leftColor'}
|
||||
- {$ref: '#/components/parameters/rightColor'}
|
||||
responses:
|
||||
"200": {description: Human-readable HTML declaration}
|
||||
"403": {$ref: '#/components/responses/ProRequired'}
|
||||
/v1/declaration.json:
|
||||
get:
|
||||
summary: Generate a JSON-LD declaration from query parameters
|
||||
parameters:
|
||||
- {$ref: '#/components/parameters/preset'}
|
||||
- {$ref: '#/components/parameters/extent'}
|
||||
- {$ref: '#/components/parameters/language'}
|
||||
- {$ref: '#/components/parameters/component'}
|
||||
- {$ref: '#/components/parameters/activities'}
|
||||
- {$ref: '#/components/parameters/review'}
|
||||
- {name: subject, in: query, schema: {type: string, format: uri}}
|
||||
- {name: responsible, in: query, schema: {type: string, maxLength: 200}}
|
||||
- {name: responsibleUrl, in: query, schema: {type: string, format: uri}}
|
||||
- {$ref: '#/components/parameters/assurance'}
|
||||
- {$ref: '#/components/parameters/customTitle'}
|
||||
- {$ref: '#/components/parameters/customDescription'}
|
||||
- {$ref: '#/components/parameters/badgeLabel'}
|
||||
- {$ref: '#/components/parameters/badgeMessage'}
|
||||
- {$ref: '#/components/parameters/leftColor'}
|
||||
- {$ref: '#/components/parameters/rightColor'}
|
||||
responses:
|
||||
"200":
|
||||
description: JSON-LD declaration
|
||||
content:
|
||||
application/ld+json:
|
||||
schema: {$ref: './schema/declaration.schema.json'}
|
||||
"403": {$ref: '#/components/responses/ProRequired'}
|
||||
/v1/validate:
|
||||
post:
|
||||
summary: Validate an AI usage declaration
|
||||
requestBody:
|
||||
required: true
|
||||
content:
|
||||
application/json:
|
||||
schema: {$ref: './schema/declaration.schema.json'}
|
||||
responses:
|
||||
"200": {description: Valid declaration}
|
||||
"422": {description: Validation failed}
|
||||
/v1/capabilities:
|
||||
get:
|
||||
summary: Return edition, licensed features and supported languages
|
||||
responses:
|
||||
"200":
|
||||
description: Runtime capabilities
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
type: object
|
||||
properties:
|
||||
license: {type: object}
|
||||
supportedLanguages:
|
||||
type: array
|
||||
items: {type: string}
|
||||
/healthz:
|
||||
get:
|
||||
summary: Liveness endpoint
|
||||
responses: {"200": {description: Healthy}}
|
||||
/readyz:
|
||||
get:
|
||||
summary: Readiness endpoint
|
||||
responses: {"200": {description: Ready}}
|
||||
components:
|
||||
parameters:
|
||||
preset:
|
||||
name: preset
|
||||
in: query
|
||||
schema: {type: string, enum: [no-ai, research, summary, full]}
|
||||
extent:
|
||||
name: extent
|
||||
in: query
|
||||
schema: {type: string, enum: [none, assisted, partial, mostly, full], default: assisted}
|
||||
language:
|
||||
name: lang
|
||||
in: query
|
||||
schema: {type: string, enum: [de, en, fr, es, it, nl, pt, pl]}
|
||||
component:
|
||||
name: component
|
||||
in: query
|
||||
schema: {type: string, enum: [text, coverImage, image, audio, video, code, other], default: text}
|
||||
activities:
|
||||
name: activities
|
||||
in: query
|
||||
schema: {type: string, description: Comma-separated activity identifiers.}
|
||||
review:
|
||||
name: review
|
||||
in: query
|
||||
schema: {type: string, enum: [none, basic, editorial, expert], default: editorial}
|
||||
assurance:
|
||||
name: assurance
|
||||
in: query
|
||||
description: Evidence basis for the declaration.
|
||||
schema: {type: string, enum: [selfDeclared, technicallyRecorded, signed, verified], default: selfDeclared}
|
||||
theme:
|
||||
name: theme
|
||||
in: query
|
||||
schema: {type: string, enum: [mono, color], default: color}
|
||||
style:
|
||||
name: style
|
||||
in: query
|
||||
schema: {type: string, enum: [flat, flat-square], default: flat}
|
||||
customTitle:
|
||||
name: customTitle
|
||||
in: query
|
||||
description: Licensed feature custom_text
|
||||
schema: {type: string, maxLength: 120}
|
||||
customDescription:
|
||||
name: customDescription
|
||||
in: query
|
||||
description: Licensed feature custom_text
|
||||
schema: {type: string, maxLength: 500}
|
||||
badgeLabel:
|
||||
name: badgeLabel
|
||||
in: query
|
||||
description: Licensed feature custom_badge
|
||||
schema: {type: string, maxLength: 40}
|
||||
badgeMessage:
|
||||
name: badgeMessage
|
||||
in: query
|
||||
description: Licensed feature custom_badge
|
||||
schema: {type: string, maxLength: 80}
|
||||
leftColor:
|
||||
name: leftColor
|
||||
in: query
|
||||
description: Licensed feature custom_badge
|
||||
schema: {type: string, pattern: '^#[0-9A-Fa-f]{6}$'}
|
||||
rightColor:
|
||||
name: rightColor
|
||||
in: query
|
||||
description: Licensed feature custom_badge
|
||||
schema: {type: string, pattern: '^#[0-9A-Fa-f]{6}$'}
|
||||
responses:
|
||||
ProRequired:
|
||||
description: A valid licensed capability is required
|
||||
content:
|
||||
application/problem+json:
|
||||
schema:
|
||||
type: object
|
||||
properties:
|
||||
code: {const: pro_feature_required}
|
||||
status: {const: 403}
|
||||
detail: {type: string}
|
||||
Reference in New Issue
Block a user