openapi: 3.0.3
info:
  title: ConceptNet REST 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: Concepts
    description: Look up concept nodes in the knowledge graph
  - name: Edges
    description: Access individual edge (assertion) records
  - name: Relations
    description: Browse edges grouped by relation type
  - name: Sources
    description: Access provenance and source information
  - name: Query
    description: Complex multi-parameter edge queries
  - name: Similarity
    description: Semantic similarity and relatedness using Numberbatch embeddings
  - name: Utilities
    description: URI normalization and text standardization

paths:
  /c/{language}/{term}:
    get:
      operationId: getConcept
      summary: Look up a concept node
      description: >-
        Returns a JSON-LD node object for the concept identified by language
        and term. The response includes all edges (assertions) connecting the
        concept to other concepts, paginated via offset and limit. The term
        may include underscores in place of spaces and an optional sense
        disambiguation suffix (e.g. /c/en/lead/n for the noun sense of "lead").
      tags:
        - Concepts
      parameters:
        - $ref: '#/components/parameters/language'
        - $ref: '#/components/parameters/term'
        - $ref: '#/components/parameters/offset'
        - $ref: '#/components/parameters/limit'
        - name: grouped
          in: query
          description: >-
            When true, groups edges by relation type rather than returning a
            flat list.
          required: false
          schema:
            type: boolean
            default: false
      responses:
        '200':
          description: Concept node with edges
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConceptNode'
              example:
                '@context': ['http://api.conceptnet.io/ld/conceptnet5.7/context.ld.json']
                '@id': '/c/en/example'
                edges:
                  - '@id': '/a/[/r/IsA/,/c/en/example/,/c/en/instance/]'
                    start:
                      '@id': '/c/en/example'
                      label: example
                      language: en
                      term: '/c/en/example'
                    end:
                      '@id': '/c/en/instance'
                      label: instance
                      language: en
                      term: '/c/en/instance'
                    rel:
                      '@id': '/r/IsA'
                      label: IsA
                    weight: 3.46
                    license: 'cc:by/4.0'
                    dataset: '/d/verbosity'
                view:
                  '@id': '/c/en/example?offset=0&limit=20'
                  paginatedProperty: edges
                  firstPage: '/c/en/example?offset=0&limit=20'
                  nextPage: '/c/en/example?offset=20&limit=20'
                  comment: 'Results 1-20 of 143'
        '404':
          description: Concept not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

  /c/{language}/{term}/{sense}:
    get:
      operationId: getConceptSense
      summary: Look up a sense-disambiguated concept node
      description: >-
        Returns a JSON-LD node object for a specific word sense of the concept.
        The sense component is a part-of-speech tag (n, v, a, r) or a more
        specific sense identifier. For example, /c/en/lead/n returns the noun
        sense of "lead" while /c/en/lead/v returns the verb sense.
      tags:
        - Concepts
      parameters:
        - $ref: '#/components/parameters/language'
        - $ref: '#/components/parameters/term'
        - name: sense
          in: path
          description: Part-of-speech tag or sense identifier (e.g. n, v, a, r)
          required: true
          schema:
            type: string
            example: n
        - $ref: '#/components/parameters/offset'
        - $ref: '#/components/parameters/limit'
      responses:
        '200':
          description: Sense-specific concept node with edges
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConceptNode'
        '404':
          description: Concept or sense not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

  /a/{edgeId}:
    get:
      operationId: getEdge
      summary: Look up an individual edge (assertion)
      description: >-
        Returns a JSON-LD edge object for the assertion identified by edgeId.
        Edge IDs are constructed from the start URI, relation URI, and end URI
        in the form /a/[/{rel}/,{start},/{end}/]. Each edge carries a weight,
        license, dataset, and source attribution.
      tags:
        - Edges
      parameters:
        - name: edgeId
          in: path
          description: Edge identifier path (URL-encoded brackets and slashes)
          required: true
          schema:
            type: string
            example: '[/r/IsA/,/c/en/example/,/c/en/instance/]'
      responses:
        '200':
          description: Edge assertion object
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Edge'
        '404':
          description: Edge not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

  /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'

  /s/{sourcePath}:
    get:
      operationId: getSource
      summary: Look up a data source
      description: >-
        Returns information about a ConceptNet data source such as
        Open Mind Common Sense, Wiktionary, WordNet, or a specific contributor.
        Source URIs take the form /s/resource/{dataset} or
        /s/contributor/omcs/{username}.
      tags:
        - Sources
      parameters:
        - name: sourcePath
          in: path
          description: Source path (e.g. resource/wordnet/3.1 or contributor/omcs/johndoe)
          required: true
          schema:
            type: string
            example: resource/wordnet/3.1
        - $ref: '#/components/parameters/offset'
        - $ref: '#/components/parameters/limit'
      responses:
        '200':
          description: Source node with provenance information
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SourceNode'
        '404':
          description: Source not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

  /query:
    get:
      operationId: queryEdges
      summary: Query edges with multiple criteria
      description: >-
        Performs a complex query against the ConceptNet edge store using any
        combination of start, end, rel, node, other, and sources parameters.
        All parameters are optional but at least one must be provided. Results
        are returned as a paginated JSON-LD edge list. This is the most flexible
        endpoint for slicing the knowledge graph by subject, object, relation
        type, or data source simultaneously.
      tags:
        - Query
      parameters:
        - name: start
          in: query
          description: ConceptNet URI for the subject (start) node of edges
          required: false
          schema:
            type: string
            example: /c/en/dog
        - name: end
          in: query
          description: ConceptNet URI for the object (end) node of edges
          required: false
          schema:
            type: string
            example: /c/en/animal
        - name: rel
          in: query
          description: Relation URI to filter by (e.g. /r/IsA or /r/UsedFor)
          required: false
          schema:
            type: string
            example: /r/IsA
        - name: node
          in: query
          description: >-
            URI matching either the start or end position of edges. Cannot be
            combined with the "other" parameter using the same URI.
          required: false
          schema:
            type: string
            example: /c/en/music
        - name: other
          in: query
          description: >-
            URI matching the position opposite to "node". Used together with
            "node" to find edges where node appears on one side and other
            appears on the other.
          required: false
          schema:
            type: string
        - name: sources
          in: query
          description: Source URI to restrict results to a specific data source
          required: false
          schema:
            type: string
            example: /s/resource/wordnet/3.1
        - $ref: '#/components/parameters/offset'
        - $ref: '#/components/parameters/limit'
      responses:
        '200':
          description: Paginated list of matching edges
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EdgeList'
        '400':
          description: Invalid query parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

  /related/{uri}:
    get:
      operationId: getRelatedConcepts
      summary: Find semantically related concepts
      description: >-
        Returns a ranked list of concepts most semantically related to the
        given URI, using ConceptNet Numberbatch word vector similarity. Results
        are sorted by descending relatedness weight. This endpoint and
        /relatedness each count as 2 requests against the rate limit quota
        (3,600 req/hour, 120 req/min). The optional filter parameter restricts
        results to a particular language subtree.
      tags:
        - Similarity
      parameters:
        - name: uri
          in: path
          description: >-
            ConceptNet URI path (e.g. c/en/dog — the leading slash is part of
            the base path, so omit it here)
          required: true
          schema:
            type: string
            example: c/en/dog
        - name: limit
          in: query
          description: Maximum number of related concepts to return (0-100)
          required: false
          schema:
            type: integer
            minimum: 0
            maximum: 100
            default: 50
        - name: filter
          in: query
          description: >-
            Restrict results to URIs under this prefix (e.g. /c/en to limit
            to English concepts)
          required: false
          schema:
            type: string
            example: /c/en
      responses:
        '200':
          description: Ranked list of related concepts with weights
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RelatedList'
              example:
                '@id': '/related/c/en/dog'
                related:
                  - '@id': '/c/en/puppy'
                    weight: 0.713
                  - '@id': '/c/en/canine'
                    weight: 0.698
                  - '@id': '/c/en/pet'
                    weight: 0.621
        '404':
          description: URI not found in embedding space
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

  /relatedness:
    get:
      operationId: getRelatedness
      summary: Compute pairwise relatedness score
      description: >-
        Returns a single floating-point relatedness score between 0 and 1 for
        any two ConceptNet concept URIs, computed from Numberbatch word vector
        cosine similarity. A score of 1.0 indicates maximum similarity and 0.0
        indicates no detectable relationship. This endpoint and /related each
        count as 2 requests against the rate limit quota.
      tags:
        - Similarity
      parameters:
        - name: node1
          in: query
          description: First ConceptNet concept URI
          required: true
          schema:
            type: string
            example: /c/en/dog
        - name: node2
          in: query
          description: Second ConceptNet concept URI
          required: true
          schema:
            type: string
            example: /c/en/cat
      responses:
        '200':
          description: Relatedness result
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RelatednessResult'
              example:
                '@id': '/relatedness?node1=/c/en/dog&node2=/c/en/cat'
                value: 0.849
                node1:
                  '@id': '/c/en/dog'
                node2:
                  '@id': '/c/en/cat'
        '400':
          description: Missing or invalid node parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

  /uri:
    get:
      operationId: normalizeUri
      summary: Normalize text to a ConceptNet URI
      description: >-
        Converts a raw natural-language phrase in any supported language into
        a canonical ConceptNet URI. Handles tokenization, lowercasing,
        stopword removal, and language-specific normalization. The resulting
        URI can be used directly in other API endpoints. Also accessible as
        /normalize and /standardize.
      tags:
        - Utilities
      parameters:
        - name: text
          in: query
          description: Natural-language phrase to normalize (use "text" or "term")
          required: false
          schema:
            type: string
            example: french toast
        - name: term
          in: query
          description: Alternative parameter name for the phrase to normalize
          required: false
          schema:
            type: string
        - name: language
          in: query
          description: BCP-47 language code for the input text
          required: true
          schema:
            type: string
            example: en
      responses:
        '200':
          description: Normalized ConceptNet URI
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UriResult'
              example:
                '@id': '/uri?language=en&text=french+toast'
                uri: '/c/en/french_toast'
        '400':
          description: Missing language or text parameter
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

components:
  parameters:
    language:
      name: language
      in: path
      description: BCP-47 language code (e.g. en, fr, de, zh, ja, es)
      required: true
      schema:
        type: string
        example: en

    term:
      name: term
      in: path
      description: >-
        Concept term in the given language, with spaces replaced by underscores
        (e.g. french_toast, dog, run_away)
      required: true
      schema:
        type: string
        example: dog

    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

  schemas:
    ConceptNode:
      type: object
      description: JSON-LD node object representing a ConceptNet concept
      properties:
        '@context':
          type: array
          items:
            type: string
          description: JSON-LD context URLs
          example:
            - 'http://api.conceptnet.io/ld/conceptnet5.7/context.ld.json'
        '@id':
          type: string
          description: ConceptNet URI of the concept
          example: /c/en/dog
        edges:
          type: array
          items:
            $ref: '#/components/schemas/Edge'
          description: List of assertions connecting this concept to others
        view:
          $ref: '#/components/schemas/Pagination'

    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'

    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

    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

    SourceRef:
      type: object
      description: Reference to a data source or contributor
      properties:
        '@id':
          type: string
          description: Source URI
          example: /s/resource/verbosity

    SourceNode:
      type: object
      description: JSON-LD node representing a ConceptNet data source
      properties:
        '@context':
          type: array
          items:
            type: string
        '@id':
          type: string
          description: Source URI
          example: /s/resource/wordnet/3.1
        edges:
          type: array
          items:
            $ref: '#/components/schemas/Edge'
        view:
          $ref: '#/components/schemas/Pagination'

    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'

    RelatedList:
      type: object
      description: Ranked list of semantically related concepts
      properties:
        '@id':
          type: string
          description: URI of this related-terms result
          example: /related/c/en/dog
        related:
          type: array
          items:
            $ref: '#/components/schemas/WeightedConcept'

    WeightedConcept:
      type: object
      description: A concept with a numeric relatedness weight
      properties:
        '@id':
          type: string
          description: ConceptNet URI of the related concept
          example: /c/en/puppy
        weight:
          type: number
          format: float
          description: Relatedness score (0.0-1.0)
          example: 0.713

    RelatednessResult:
      type: object
      description: Pairwise semantic relatedness result
      properties:
        '@id':
          type: string
          description: URI of this relatedness result
        value:
          type: number
          format: float
          description: Relatedness score between 0.0 and 1.0
          example: 0.849
        node1:
          $ref: '#/components/schemas/ConceptRef'
        node2:
          $ref: '#/components/schemas/ConceptRef'

    UriResult:
      type: object
      description: URI normalization result
      properties:
        '@id':
          type: string
          description: URI of this normalization result
        uri:
          type: string
          description: Canonical ConceptNet URI for the input text
          example: /c/en/french_toast

    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'

    Error:
      type: object
      description: API error response
      properties:
        error:
          type: string
          description: Error type identifier
        details:
          type: string
          description: Human-readable error description