openapi: 3.0.3
info:
  title: ConceptNet REST Concepts Relations API
  description: ConceptNet is a freely available multilingual knowledge graph providing computers access to common-sense knowledge. The REST API exposes the full ConceptNet 5 knowledge graph via JSON-LD endpoints. Consumers can look up concept nodes by language and term, query edges by relation type, retrieve semantically related terms ranked by Numberbatch embedding similarity, compute pairwise relatedness scores between concepts, and normalize natural-language text into canonical ConceptNet URIs. No authentication or API key is required.
  version: '5.7'
  license:
    name: CC BY-SA 4.0
    url: https://creativecommons.org/licenses/by-sa/4.0/
  contact:
    name: ConceptNet Users Group
    url: https://groups.google.com/g/conceptnet-users
  x-website: https://conceptnet.io
  x-github: https://github.com/commonsense/conceptnet5
servers:
- url: https://api.conceptnet.io
  description: ConceptNet public API
tags:
- name: Relations
  description: Browse edges grouped by relation type
paths:
  /r/{relation}:
    get:
      operationId: getRelation
      summary: Browse edges by relation type
      description: Returns a paginated JSON-LD list of all edges using the specified relation type. Valid relation names include IsA, UsedFor, CapableOf, AtLocation, Causes, HasProperty, PartOf, SimilarTo, Antonym, RelatedTo, DerivedFrom, Synonym, and many others defined in the ConceptNet relation vocabulary.
      tags:
      - Relations
      parameters:
      - name: relation
        in: path
        description: ConceptNet relation name (e.g. IsA, UsedFor, RelatedTo)
        required: true
        schema:
          type: string
          example: IsA
      - $ref: '#/components/parameters/offset'
      - $ref: '#/components/parameters/limit'
      responses:
        '200':
          description: Paginated list of edges with the given relation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EdgeList'
        '404':
          description: Relation not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  schemas:
    RelationRef:
      type: object
      description: Reference to a ConceptNet relation type
      properties:
        '@id':
          type: string
          description: Relation URI
          example: /r/IsA
        label:
          type: string
          description: Human-readable relation name
          example: IsA
    Error:
      type: object
      description: API error response
      properties:
        error:
          type: string
          description: Error type identifier
        details:
          type: string
          description: Human-readable error description
    EdgeList:
      type: object
      description: Paginated list of edges
      properties:
        '@context':
          type: array
          items:
            type: string
        '@id':
          type: string
          description: URI of this query result
        edges:
          type: array
          items:
            $ref: '#/components/schemas/Edge'
        view:
          $ref: '#/components/schemas/Pagination'
    SourceRef:
      type: object
      description: Reference to a data source or contributor
      properties:
        '@id':
          type: string
          description: Source URI
          example: /s/resource/verbosity
    ConceptRef:
      type: object
      description: Reference to a ConceptNet concept node
      properties:
        '@id':
          type: string
          description: ConceptNet URI
          example: /c/en/dog
        label:
          type: string
          description: Human-readable label
          example: dog
        language:
          type: string
          description: BCP-47 language code
          example: en
        term:
          type: string
          description: Concept URI (same as @id)
          example: /c/en/dog
        sense_label:
          type: string
          description: Part-of-speech or sense label if applicable
          example: n
    Edge:
      type: object
      description: A single ConceptNet assertion (knowledge edge)
      properties:
        '@id':
          type: string
          description: Unique URI identifier for this edge
          example: /a/[/r/IsA/,/c/en/dog/,/c/en/animal/]
        start:
          $ref: '#/components/schemas/ConceptRef'
        end:
          $ref: '#/components/schemas/ConceptRef'
        rel:
          $ref: '#/components/schemas/RelationRef'
        surfaceText:
          type: string
          nullable: true
          description: Natural-language sentence the assertion was derived from
          example: '[[A dog]] is a [[animal]].'
        weight:
          type: number
          format: float
          description: Confidence weight of the assertion (typically 1.0+)
          example: 3.46
        license:
          type: string
          description: Creative Commons license identifier
          example: cc:by/4.0
        dataset:
          type: string
          description: Dataset URI this assertion came from
          example: /d/verbosity
        sources:
          type: array
          items:
            $ref: '#/components/schemas/SourceRef'
    Pagination:
      type: object
      description: Pagination metadata for list responses
      properties:
        '@id':
          type: string
          description: URI of the current page
        paginatedProperty:
          type: string
          description: Property name that contains the paginated items
          example: edges
        firstPage:
          type: string
          description: URI of the first page
        nextPage:
          type: string
          description: URI of the next page (absent on last page)
        previousPage:
          type: string
          description: URI of the previous page (absent on first page)
        comment:
          type: string
          description: Human-readable summary of current result range
          example: Results 1-20 of 143
  parameters:
    offset:
      name: offset
      in: query
      description: Number of results to skip for pagination (0-100000)
      required: false
      schema:
        type: integer
        minimum: 0
        maximum: 100000
        default: 0
    limit:
      name: limit
      in: query
      description: Maximum number of results to return (0-1000)
      required: false
      schema:
        type: integer
        minimum: 0
        maximum: 1000
        default: 20