openapi.json

{
  "openapi" : "3.0.1",
  "info" : {
    "title" : "Diffbot Enhance Service",
    "description" : "Enhance is an API to find a person or organization in the Knowledge Graph using partial data",
    "termsOfService" : "https://www.diffbot.com/terms/",
    "contact" : {
      "email" : "support@diffbot.com"
    },
    "version" : "v1.0.0",
    "x-logo" : {
      "url" : "/Diffbot_Logo.png",
      "altText" : "Diffbot logo"
    }
  },
  "servers" : [ {
    "url" : "https://kg.diffbot.com",
    "description" : "Diffbot KG endpoint"
  } ],
  "tags" : [ {
    "name" : "Bulk Enhance Endpoint",
    "description" : "Enhance Bulk Endpoint"
  }, {
    "name" : "Enhance Live Endpoint",
    "description" : "Enhance Live Endpoint"
  } ],
  "paths" : {
    "/kg/enhance_endpoint/bulk/{bulkjobId}/stop" : {
      "get" : {
        "tags" : [ "Bulk Enhance Endpoint" ],
        "summary" : "Bulkjob stop",
        "description" : "Stop an incomplete job",
        "operationId" : "stopBulkjob",
        "parameters" : [ {
          "name" : "token",
          "in" : "query",
          "description" : "Diffbot Token",
          "schema" : {
            "type" : "string"
          }
        }, {
          "name" : "bulkjobId",
          "in" : "path",
          "description" : "Bulkjob Id",
          "required" : true,
          "schema" : {
            "type" : "string"
          }
        } ],
        "responses" : {
          "200" : {
            "description" : "Enhanced entity",
            "content" : {
              "application/json" : {
                "schema" : {
                  "$ref" : "#/components/schemas/BulkjobRecoveryStatusResponse"
                }
              }
            }
          },
          "400" : {
            "description" : "Invalid bulkjobId",
            "content" : {
              "application/json" : {
                "schema" : {
                  "$ref" : "#/components/schemas/RequestError"
                }
              }
            }
          },
          "401" : {
            "description" : "Token not specified or other client errors",
            "content" : {
              "application/json" : {
                "schema" : {
                  "$ref" : "#/components/schemas/RequestError"
                }
              }
            }
          },
          "404" : {
            "description" : "Bulkjob not found",
            "content" : {
              "application/json" : {
                "schema" : {
                  "$ref" : "#/components/schemas/RequestError"
                }
              }
            }
          },
          "500" : {
            "description" : "Internal Server Error",
            "content" : {
              "application/json" : {
                "schema" : {
                  "$ref" : "#/components/schemas/RequestError"
                }
              }
            }
          }
        },
        "x-group-parameters" : true
      }
    },
    "/kg/enhance_endpoint/bulk/{bulkjobId}/status" : {
      "get" : {
        "tags" : [ "Bulk Enhance Endpoint" ],
        "summary" : "Bulk Enhance Status Endpoint",
        "description" : "Get status of a bulk Enhance job",
        "operationId" : "bulkjobStatus",
        "parameters" : [ {
          "name" : "token",
          "in" : "query",
          "description" : "Diffbot Token",
          "schema" : {
            "type" : "string"
          }
        }, {
          "name" : "bulkjobId",
          "in" : "path",
          "description" : "Bulkjob Id",
          "required" : true,
          "schema" : {
            "type" : "string"
          }
        } ],
        "responses" : {
          "200" : {
            "description" : "Bulkjob status",
            "content" : {
              "application/json" : {
                "schema" : {
                  "$ref" : "#/components/schemas/BulkjobStatusResponse"
                }
              }
            }
          },
          "201" : {
            "description" : "Bulkjob is still executing or is stopped",
            "content" : {
              "application/json" : {
                "schema" : {
                  "$ref" : "#/components/schemas/BulkjobStatusResponse"
                }
              }
            }
          },
          "400" : {
            "description" : "Invalid bulkjobId",
            "content" : {
              "application/json" : {
                "schema" : {
                  "$ref" : "#/components/schemas/RequestError"
                }
              }
            }
          },
          "401" : {
            "description" : "Token not specified or other client errors",
            "content" : {
              "application/json" : {
                "schema" : {
                  "$ref" : "#/components/schemas/RequestError"
                }
              }
            }
          },
          "404" : {
            "description" : "Bulkjob not found",
            "content" : {
              "application/json" : {
                "schema" : {
                  "$ref" : "#/components/schemas/RequestError"
                }
              }
            }
          },
          "500" : {
            "description" : "Internal Server Error",
            "content" : {
              "application/json" : {
                "schema" : {
                  "$ref" : "#/components/schemas/RequestError"
                }
              }
            }
          }
        },
        "x-group-parameters" : true
      }
    },
    "/kg/enhance_endpoint/bulk" : {
      "post" : {
        "tags" : [ "Bulk Enhance Endpoint" ],
        "summary" : "Bulk Enhance Endpoint",
        "description" : "Enhance endpoint to find person or organization using partial data",
        "operationId" : "enhanceBulkjob",
        "parameters" : [ {
          "name" : "token",
          "in" : "query",
          "description" : "Diffbot Token",
          "schema" : {
            "type" : "string"
          }
        }, {
          "name" : "tag",
          "in" : "query",
          "description" : "Tag",
          "schema" : {
            "type" : "array",
            "items" : {
              "type" : "string"
            }
          }
        }, {
          "name" : "mode",
          "in" : "query",
          "description" : "`mode=refresh` indicates that Diffbot will attempt to recrawl all the origins of the identified entity and reconstruct the returned entity from this refreshed data.",
          "schema" : {
            "type" : "string"
          }
        }, {
          "name" : "nonCanonicalFacts",
          "in" : "query",
          "description" : "`nonCanonicalFacts=true` returns non-canonical facts.",
          "schema" : {
            "type" : "string"
          }
        }, {
          "name" : "jsonmode",
          "in" : "query",
          "description" : "`jsonmode=extended` returns origin information for facts.",
          "schema" : {
            "type" : "string"
          }
        }, {
          "name" : "rocketReachToken",
          "in" : "query",
          "description" : "rocketReach token",
          "schema" : {
            "type" : "string"
          }
        }, {
          "name" : "webhookurl",
          "in" : "query",
          "description" : "Webhook URL",
          "schema" : {
            "type" : "string"
          }
        }, {
          "name" : "X-Diffbot-RequestId",
          "in" : "header",
          "description" : "Request UUID for tracking. If available, will be set on response.",
          "schema" : {
            "type" : "string"
          }
        } ],
        "requestBody" : {
          "description" : "Bulk query payload",
          "content" : {
            "application/json" : {
              "schema" : {
                "type" : "array",
                "items" : {
                  "type" : "object"
                }
              }
            }
          }
        },
        "responses" : {
          "200" : {
            "description" : "Acknowledgement with bulkjobId",
            "content" : {
              "application/json" : {
                "schema" : {
                  "$ref" : "#/components/schemas/BulkjobAccepted"
                }
              }
            }
          },
          "400" : {
            "description" : "Error parsing request",
            "content" : {
              "application/json" : {
                "schema" : {
                  "$ref" : "#/components/schemas/RequestError"
                }
              }
            }
          },
          "401" : {
            "description" : "Token not specified or other client errors",
            "content" : {
              "application/json" : {
                "schema" : {
                  "$ref" : "#/components/schemas/RequestError"
                }
              }
            }
          },
          "429" : {
            "description" : "Insufficient credits",
            "content" : {
              "application/json" : {
                "schema" : {
                  "$ref" : "#/components/schemas/RequestError"
                }
              }
            }
          },
          "500" : {
            "description" : "Internal Server Error",
            "content" : {
              "application/json" : {
                "schema" : {
                  "$ref" : "#/components/schemas/RequestError"
                }
              }
            }
          },
          "503" : {
            "description" : "Request too large",
            "content" : {
              "application/json" : {
                "schema" : {
                  "$ref" : "#/components/schemas/RequestError"
                }
              }
            }
          }
        },
        "x-group-parameters" : true
      }
    },
    "/kg/enhance_endpoint/bulk/{bulkjobId}" : {
      "get" : {
        "tags" : [ "Bulk Enhance Endpoint" ],
        "summary" : "Bulk Enhance Poll Endpoint",
        "description" : "Poll a bulk Enhance job",
        "operationId" : "pollBulkjob",
        "parameters" : [ {
          "name" : "token",
          "in" : "query",
          "description" : "Diffbot Token",
          "schema" : {
            "type" : "string"
          }
        }, {
          "name" : "bulkjobId",
          "in" : "path",
          "description" : "Bulkjob Id",
          "required" : true,
          "schema" : {
            "type" : "string"
          }
        }, {
          "name" : "csvmode",
          "in" : "query",
          "description" : "Return results as csv",
          "schema" : {
            "type" : "string"
          }
        } ],
        "responses" : {
          "200" : {
            "description" : "Enhanced entity",
            "content" : {
              "application/json" : {
                "schema" : {
                  "type" : "object"
                }
              }
            }
          },
          "201" : {
            "description" : "Bulkjob is still executing or is stopped",
            "content" : {
              "application/json" : {
                "schema" : {
                  "$ref" : "#/components/schemas/BulkjobStatusResponse"
                }
              }
            }
          },
          "400" : {
            "description" : "Invalid bulkjobId",
            "content" : {
              "application/json" : {
                "schema" : {
                  "$ref" : "#/components/schemas/RequestError"
                }
              }
            }
          },
          "401" : {
            "description" : "Token not specified or other client errors",
            "content" : {
              "application/json" : {
                "schema" : {
                  "$ref" : "#/components/schemas/RequestError"
                }
              }
            }
          },
          "404" : {
            "description" : "Bulkjob not found",
            "content" : {
              "application/json" : {
                "schema" : {
                  "$ref" : "#/components/schemas/RequestError"
                }
              }
            }
          },
          "500" : {
            "description" : "Internal Server Error",
            "content" : {
              "application/json" : {
                "schema" : {
                  "$ref" : "#/components/schemas/RequestError"
                }
              }
            }
          }
        },
        "x-group-parameters" : true
      }
    },
    "/kg/enhance_endpoint" : {
      "get" : {
        "tags" : [ "Enhance Live Endpoint" ],
        "summary" : "Live Enhance Endpoint",
        "description" : "Enhance endpoint to find person or organization using partial data",
        "operationId" : "enhance",
        "parameters" : [ {
          "name" : "token",
          "in" : "query",
          "description" : "Diffbot Token",
          "schema" : {
            "type" : "string"
          }
        }, {
          "name" : "type",
          "in" : "query",
          "description" : "Diffbot entity type",
          "schema" : {
            "type" : "string",
            "format" : "enum",
            "enum" : [ "Person", "Organization" ]
          }
        }, {
          "name" : "id",
          "in" : "query",
          "description" : "DiffbotId of entity to enhance. Parameter can be used with types `Person` and `Organization`",
          "schema" : {
            "type" : "string"
          }
        }, {
          "name" : "name",
          "in" : "query",
          "description" : "Name of the entity to enhance. Parameter can be used with types `Person` and `Organization`",
          "schema" : {
            "type" : "string"
          }
        }, {
          "name" : "url",
          "in" : "query",
          "description" : "Origin or homepage URI of entity to enhance. Parameter can be used with types `Person` and `Organization`",
          "schema" : {
            "type" : "string"
          }
        }, {
          "name" : "phone",
          "in" : "query",
          "description" : "Phone of the entity to enhance. Parameter can be used with types `Person` and `Organization`",
          "schema" : {
            "type" : "string"
          }
        }, {
          "name" : "email",
          "in" : "query",
          "description" : "Email of the entity to enhance. Parameter can be used only with type `Person`",
          "schema" : {
            "type" : "string"
          }
        }, {
          "name" : "description",
          "in" : "query",
          "description" : "Description of the entity to enhance. Parameter can be used with types `Person` and `Organization`",
          "schema" : {
            "type" : "string"
          }
        }, {
          "name" : "employer",
          "in" : "query",
          "description" : "Employer of the entity to enhance. Parameter can be used only with type `Person`",
          "schema" : {
            "type" : "string"
          }
        }, {
          "name" : "title",
          "in" : "query",
          "description" : "Title of the entity to enhance. Parameter can be used only with type `Person`",
          "schema" : {
            "type" : "string"
          }
        }, {
          "name" : "school",
          "in" : "query",
          "description" : "School of the entity to enhance. Parameter can be used only with type `Person`",
          "schema" : {
            "type" : "string"
          }
        }, {
          "name" : "location",
          "in" : "query",
          "description" : "Location of the entity to enhance. Parameter can be used with types `Person` and `Organization`",
          "schema" : {
            "type" : "string"
          }
        }, {
          "name" : "mode",
          "in" : "query",
          "description" : "`mode=refresh` indicates that Diffbot will attempt to recrawl all the origins of the identified entity and reconstruct the returned entity from this refreshed data.",
          "schema" : {
            "type" : "string"
          }
        }, {
          "name" : "nonCanonicalFacts",
          "in" : "query",
          "description" : "`nonCanonicalFacts=true` returns non-canonical facts.",
          "schema" : {
            "type" : "string"
          }
        }, {
          "name" : "jsonmode",
          "in" : "query",
          "description" : "`jsonmode=extended` returns origin information for facts.",
          "schema" : {
            "type" : "string"
          }
        }, {
          "name" : "rocketReachToken",
          "in" : "query",
          "description" : "rocketReach token",
          "schema" : {
            "type" : "string"
          }
        }, {
          "name" : "X-Diffbot-RequestId",
          "in" : "header",
          "description" : "Request UUID for tracking. If available, will be set on response.",
          "schema" : {
            "type" : "string"
          }
        } ],
        "responses" : {
          "200" : {
            "description" : "Enhanced entity",
            "content" : {
              "application/json" : {
                "schema" : {
                  "$ref" : "#/components/schemas/EnhanceResponse"
                }
              }
            }
          },
          "400" : {
            "description" : "Error parsing request",
            "content" : {
              "application/json" : {
                "schema" : {
                  "$ref" : "#/components/schemas/RequestError"
                }
              }
            }
          },
          "401" : {
            "description" : "Token not specified or other client errors",
            "content" : {
              "application/json" : {
                "schema" : {
                  "$ref" : "#/components/schemas/RequestError"
                }
              }
            }
          },
          "429" : {
            "description" : "Insufficient credits",
            "content" : {
              "application/json" : {
                "schema" : {
                  "$ref" : "#/components/schemas/RequestError"
                }
              }
            }
          },
          "500" : {
            "description" : "Internal Server Error",
            "content" : {
              "application/json" : {
                "schema" : {
                  "$ref" : "#/components/schemas/RequestError"
                }
              }
            }
          }
        },
        "x-group-parameters" : true
      }
    }
  },
  "components" : {
    "schemas" : {
      "BulkjobRecoveryStatusResponse" : {
        "type" : "object",
        "properties" : {
          "status" : {
            "type" : "string",
            "description" : "Bulkjob recovery status",
            "enum" : [ "NOT_STARTED", "IN_PROCESS", "COMPLETE", "COMPLETE_WITH_FAILURES", "STOPPED", "ERROR_FINALIZING", "UNKNOWN" ]
          },
          "message" : {
            "type" : "string",
            "description" : "Bulkjob recovery status message"
          }
        }
      },
      "RequestError" : {
        "type" : "object",
        "properties" : {
          "error" : {
            "type" : "boolean",
            "description" : "Always `true`"
          },
          "code" : {
            "type" : "integer",
            "description" : "Error code (same as the HTTP status code)",
            "format" : "int32"
          },
          "message" : {
            "type" : "string",
            "description" : "Error message"
          },
          "query" : {
            "type" : "object",
            "description" : "Submitted Enhance query"
          }
        }
      },
      "BulkjobStatus" : {
        "type" : "object",
        "properties" : {
          "job_id" : {
            "type" : "string",
            "description" : "Bulkjob Id"
          },
          "message" : {
            "type" : "string",
            "description" : "Bulkjob status message"
          },
          "jobs_total" : {
            "type" : "integer",
            "description" : "Number of jobs in bulkjob",
            "format" : "int32"
          },
          "jobs_completed" : {
            "type" : "integer",
            "description" : "Number of jobs completed in bulkjob.",
            "format" : "int32"
          },
          "status" : {
            "type" : "string",
            "description" : "Status of Bulkjob. One of {NOT_STARTED, IN_PROCESS, COMPLETE, COMPLETE_WITH_FAILURES, STOPPED, ERROR_FINALIZING, UNKNOWN}",
            "enum" : [ "NOT_STARTED", "IN_PROCESS", "COMPLETE", "COMPLETE_WITH_FAILURES", "STOPPED", "ERROR_FINALIZING", "UNKNOWN" ]
          },
          "estimate_remaining_time" : {
            "type" : "integer",
            "description" : "Estimated remaining time for bulkjob to complete (in seconds). `null` if job is completed or not started.",
            "format" : "int64"
          }
        },
        "description" : "Bulkjob status"
      },
      "BulkjobStatusResponse" : {
        "type" : "object",
        "properties" : {
          "code" : {
            "type" : "integer",
            "description" : "Bulkjob status code (same as the HTTP status code)",
            "format" : "int32"
          },
          "content" : {
            "$ref" : "#/components/schemas/BulkjobStatus"
          }
        }
      },
      "BulkjobAccepted" : {
        "type" : "object",
        "properties" : {
          "job_id" : {
            "type" : "string",
            "description" : "Bulkjob Id for checking status and downloading results"
          }
        }
      },
      "EnhanceResponse" : {
        "type" : "object",
        "properties" : {
          "score" : {
            "type" : "object",
            "description" : "Enhance score"
          },
          "enhanced" : {
            "type" : "object",
            "description" : "Enhanced entity. Can be null if no entity was found."
          },
          "query" : {
            "type" : "object",
            "description" : "Submitted Enhance query"
          },
          "warnings" : {
            "type" : "object",
            "description" : "Any warnings while enhancing entity"
          }
        }
      }
    }
  }
}