api.yml

# Copyright 2024 Google LLC
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
#     http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.

---
openapi: 3.0.1

info:
  title: Altitude API
  description: API to manage signals and targets in an Altitude server.
  version: "1.0"

servers:
  - url: http://localhost:80/api/
    description: Example URL when running locally.

paths:
  /targets/:
    post:
      description: |
        Creates a new Target entity reflecting content submitted for scanning.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                title:
                  type: string
                description:
                  type: string
                views:
                  type: number
                creator:
                  $ref: "#/components/schemas/Creator"
                client_context:
                  description: |
                    An opaque string that will be associated with the entity
                    throughout the pipeline.
                  type: string
                content_type:
                  type: string
                  enum:
                    - IMAGE
                    - TEXT
                content_bytes:
                  description: The target content, encoded as a base64 string.
                  type: string
                  format: byte # base64-encoded file contents
              required:
                - content_type
                - content_bytes
            examples:
              "image":
                value: >-
                  {
                    "client_context": "my identifier",
                    "content_type": "IMAGE",
                    "content_bytes": "R0lGODlhAQABAAAAACH5BAEKAAEALAAAAAABAAEAAAICTAEAOw=="
                  }
      responses:
        "201":
          description: The target was successfully created.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Target"
              examples:
                "image":
                  value: >-
                    {"id": "123abc", "create_time": "2024-06-20T21:33:54.564687", "client_context": "my identifier", "content_bytes": "R0lGODlhAQABAAAAACH5BAEKAAEALAAAAAABAAEAAAICTAEAOw==", "safe_search_scores": {"adult": "UNKNOWN", "spoof": "UNKNOWN", "medical": "UNKNOWN", "violence": "UNKNOWN", "racy": "UNKNOWN"}}⏎
        "400":
          description: An invalid request was provided.
        "500":
          description: An internal error occurred.

  /targets/{id}:
    get:
      description: Returns a single Target entity by its unique identifier.
      parameters:
        - name: id
          in: path
          required: true
          description: The id to get the entity.
          schema:
            type: string
      responses:
        "200":
          description: The target.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Target"
              examples:
                "image":
                  value: >-
                    {"id": "123abc", "create_time": "2024-06-20T21:33:54.564687", "client_context": "my identifier", "content_bytes": "R0lGODlhAQABAAAAACH5BAEKAAEALAAAAAABAAEAAAICTAEAOw==", "safe_search_scores": {"adult": "UNKNOWN", "spoof": "UNKNOWN", "medical": "UNKNOWN", "violence": "UNKNOWN", "racy": "UNKNOWN"}}⏎
        "404":
          description: Target inexistent.
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: string
                  message:
                    type: string
              examples:
                "0":
                  value: >-
                    {"code":"NotFoundError","message":"Target 456def not found"}
        "500":
          description: An internal error occurred.

    patch:
      description: Updates a single Target entity by its unique identifier.
      parameters:
        - name: id
          in: path
          required: true
          description: The id to get the entity.
          schema:
            type: string
      responses:
        "200":
          description: The updated target.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Target"
              examples:
                "image":
                  value: >-
                    {"id": "123abc", "create_time": "2024-06-20T21:33:54.564687", "client_context": "my identifier", "content_bytes": "R0lGODlhAQABAAAAACH5BAEKAAEALAAAAAABAAEAAAICTAEAOw==", "safe_search_scores": {"adult": "UNKNOWN", "spoof": "UNKNOWN", "medical": "UNKNOWN", "violence": "UNKNOWN", "racy": "UNKNOWN"}}⏎
        "404":
          description: Target inexistent.
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: string
                  message:
                    type: string
              examples:
                "0":
                  value: >-
                    {"code":"NotFoundError","message":"Target 456def not found"}
        "500":
          description: An internal error occurred.

  /signals/:
    get:
      description: Returns a list of Signal entities.
      responses:
        "200":
          description: The signals.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/Signal"
              examples:
                "PDQ hash":
                  value: >-
                    [
                      {"id": "123abc", "create_time": "2024-06-20T22:24:54", "content": [{"value": "000000000000000000000000000000000000000000000000000000000000ffff", "content_type": "HASH_PDQ"}], "sources": [{"name": "USER_REPORT", "create_time": "2024-06-20T22:24:54", "author": "JigsawTest Hash Sharing"}]},
                      {"id": "123abc", "create_time": "2024-06-21T03:14:11", "content": [{"value": "0000000000000000000000000000000000000000000000000000000000000000", "content_type": "HASH_PDQ"}], "sources": [{"name": "USER_REPORT", "create_time": "2024-06-21T03:14:11", "author": "JigsawTest Hash Sharing"}]}
                    ]
        "500":
          description: An internal error occurred.

    post:
      description: |
        Creates a new Signal entity that can be used to identify new content for review.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                content:
                  type: object
                  properties:
                    value:
                      type: string
                    type:
                      type: string
                      enum:
                        - HASH_PDQ
                        - HASH_MD5
                        - URL
                  required:
                    - value
                    - type
                source:
                  type: object
                  properties:
                    name:
                      type: string
                      enum:
                        - TCAP
                        - GIFCT
                        - USER_REPORT
                    author:
                      type: string
                    create_time:
                      type: string
                      format: date-time
                  required:
                    - name
              required:
                - content
            examples:
              "PDQ hash":
                value: >-
                  {
                    "content": {
                      "value: "000000000000000000000000000000000000000000000000000000000000ffff",
                      "type": "HASH_PDQ"
                    },
                    "source": {
                      "name": "USER_REPORT",
                      "author": "JigsawTest Hash Sharing",
                      "create_time": "2024-06-20T22:24:54"
                    }
                  }
      responses:
        "201":
          description: The signal was successfully created.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Signal"
              examples:
                "PDQ hash":
                  value: >-
                    {"id": "123abc", "create_time": "2024-06-20T22:24:54", "content": [{"value": "000000000000000000000000000000000000000000000000000000000000ffff", "content_type": "HASH_PDQ"}], "sources": [{"name": "USER_REPORT", "create_time": "2024-06-20T22:24:54", "author": "JigsawTest Hash Sharing"}]}⏎
        "400":
          description: An invalid request was provided.
        "500":
          description: An internal error occurred.

  /signals/{id}:
    get:
      description: Returns a single Signal entity by its unique identifier.
      parameters:
        - name: id
          in: path
          required: true
          description: The id to get the entity.
          schema:
            type: string
      responses:
        "200":
          description: The signal.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Signal"
              examples:
                "PDQ hash":
                  value: >-
                    {"id": "123abc", "create_time": "2024-06-20T22:24:54", "content": [{"value": "000000000000000000000000000000000000000000000000000000000000ffff", "content_type": "HASH_PDQ"}], "sources": [{"name": "USER_REPORT", "create_time": "2024-06-20T22:24:54", "author": "JigsawTest Hash Sharing"}]}⏎
        "404":
          description: Signal inexistent.
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: string
                  message:
                    type: string
              examples:
                "0":
                  value: >-
                    {"code":"NotFoundError","message":"Signal 456def not found"}
        "500":
          description: An internal error occurred.

components:
  schemas:
    Target:
      properties:
        id:
          type: string
        create_time:
          type: string
          format: date-time
        title:
          type: string
        description:
          type: string
        views:
          type: number
        content_bytes:
          description: The target content, encoded as a base64 string.
          type: string
          format: byte # base64-encoded file contents
        creator:
          $ref: "#/components/schemas/Creator"
        client_context:
          description: An opaque string that will be associated with the entity throughout the pipeline.
          type: string
        safe_search_scores:
          type: object
          properties:
            adult:
              $ref: "#/components/schemas/SafeSearchScore"
            spoof:
              $ref: "#/components/schemas/SafeSearchScore"
            medical:
              $ref: "#/components/schemas/SafeSearchScore"
            violence:
              $ref: "#/components/schemas/SafeSearchScore"
            racy:
              $ref: "#/components/schemas/SafeSearchScore"
      required:
        - id
        - create_time
    Creator:
      properties:
        ip_address:
          type: string
          oneOf:
            - format: ipv4
            - format: ipv6
            - format: hostname
    Signal:
      properties:
        id:
          type: string
        create_time:
          type: string
          format: date-time
          nullable: true
        content:
          type: array
          items:
            type: object
            properties:
              value:
                type: string
              content_type:
                type: string
                enum:
                  - URL
                  - HASH_PDQ
                  - HASH_MD5
                  - API
                  - UNKNOWN
        sources:
          type: array
          items:
            type: object
            properties:
              name:
                type: string
                enum:
                  - TCAP
                  - GIFCT
                  - USER_REPORT
                  - SAFE_SEARCH
                  - PERSPECTIVE
                  - UNKNOWN
              author:
                type: string
                nullable: true
              create_time:
                type: string
                format: date-time
                nullable: true
            required:
              - name
        content_features:
          type: object
          properties:
            associated_entities:
              type: array
              items:
                type: string
            contains_pii:
              $ref: "#/components/schemas/Confidence"
            is_violent_or_graphic":
              $ref: "#/components/schemas/Confidence"
            is_illegal_in_countries:
              type: array
              items:
                type: string
            tags:
              type: array
              items:
                type: string
        status:
          type: object
          properties:
            last_checked_time:
              type: string
              format: date-time
              nullable: true
            verifier:
              type: string
            most_recent_status:
              type: string
              enum:
                - UNKNOWN
                - ACTIVE
                - REMOVED_BY_USER
                - REMOVED_BY_MODERATOR
                - UNAVAILABLE
              nullable: true
    SafeSearchScore:
      type: string
      enum:
        - UNKNOWN
        - VERY_UNLIKELY
        - UNLIKELY
        - POSSIBLE
        - LIKELY
        - VERY_LIKELY
    Confidence:
      type: string
      enum:
        - YES
        - NO
        - UNSURE
      nullable: true