NAV Navbar
shell ruby python javascript
  • Overview
  • Getting started
  • API
  • Errors
  • Overview

    The Craft API provides developer access to the Craft data platform.

    Craft API is a GraphQL API build over HTTP. GraphQL makes it possible to make a single API call to fetch all the information on a particular company you need.

    Getting started

    To use the Craft API you will need an API Access key.

    Get API Key

    API

    Example

    Let’s get location information for Facebook based on their website domain name.

    
    require 'net/http'
    require 'json'
    
    API_KEY = "qfNfdijpFhbhPhA7j2ZxvtEGkfv8DftTtmTEbnWN"
    API_ENDPOINT = "https://api.craft.co/v1/query"
    GRAPHQL_QUERY = "query getCompany($domain: String!) { company(domain: $domain) { locations { city, country } } }"
    
    request_headers= { "Content-Type": "application/json", "x-craft-api-key": API_KEY }
    request_data = {
        "query": GRAPHQL_QUERY,
        "variables": { "domain": "facebook.com" }
    }
    
    response = Net::HTTP.post(URI(API_ENDPOINT), request_data.to_json, request_headers)
    puts response.body
    
    
    import requests
    
    API_KEY = "qfNfdijpFhbhPhA7j2ZxvtEGkfv8DftTtmTEbnWN"
    API_ENDPOINT = "https://api.craft.co/v1/query"
    GRAPHQL_QUERY = """ query getCompany($domain: String!) { company(domain: $domain) { locations { city, country } } } """
    
    request_headers= { "x-craft-api-key": API_KEY }
    request_data = {
        "query": GRAPHQL_QUERY,
        "variables": { "domain": "facebook.com" }
    }
    
    response = requests.post(API_ENDPOINT, json=request_data, headers=request_headers, timeout=30)
    response_data = response.json()
    
    print(response_data)
    
    curl --request POST \
      --url 'https://api.craft.co/v1/query?=' \
      --header 'content-type: application/json' \
      --header 'x-craft-api-key: qfNfdijpFhbhPhA7j2ZxvtEGkfv8DftTtmTEbnWN' \
      --data '{"query":"query getCompany($domain: String!) {\n\tcompany(domain: $domain) {\n\t\t locations {\n\t\t\tcity,\n\t\t\tcountry\n\t\t} \n\t}\n}","variables":{"domain":"facebook.com"},"operationName":"getCompany"}'
    
    
    
    require('isomorphic-fetch');
    
    API_KEY = 'qfNfdijpFhbhPhA7j2ZxvtEGkfv8DftTtmTEbnWN';
    API_ENDPOINT = 'https://api.craft.co/v1/query';
    GRAPHQL_QUERY = 'query getCompany($domain: String!) { company(domain: $domain) { locations { city, country } } }';
    
    requestHeaders= { 'Content-Type': 'application/json', 'x-craft-api-key': API_KEY };
    requestData = { 'query': GRAPHQL_QUERY, 'variables': { 'domain': 'facebook.com' } };
    
    fetch(API_ENDPOINT, {
        method: 'POST',
        headers: requestHeaders,
        body: JSON.stringify(requestData),
    })
        .then(function(response)  { return response.json() })
        .then(console.log)
        .catch(console.error);
    

    Make sure to replace qfNfdijpFhbhPhA7j2ZxvtEGkfv8DftTtmTEbnWN with your API key.

    The above command returns JSON structured like this:

    {
      "data": {
        "company": {
          "locations": [
            {
              "city": "Tokyo",
              "country": "JP"
            },
            {
              "city": "Ottawa",
              "country": "CA"
            },
            {
              "city": "Jakarta",
              "country": "ID"
            },
           ... 
          ]
        }
      }
    }
    

    API Reference

    The reference documents for version 1.0 of our API can be found here, and are automatically generated from the Craft API schema.

    Authorization

    To maintain API access, please provide your API Access key in the header with every HTTP request

    x-craft-api-key: YOUR_API_KEY

    Usage

    Schema endpoint

    POST https://api.craft.co/v1/schema

    Query endpoint

    Use query as the root request object.

    POST https://api.craft.co/v1/query

    Response format

    Reponse format for a query request is JSON. In case of successful request that would be a nested strcuture wrapped with data key:

    { "data": { ... } }

    In case of an error:

    { "errors": [ ... ] }

    Errors

    Craft API uses the following HTTP error codes:

    Error Code Meaning
    200 OK - Everything went well
    401 Unauthorized - Your API key is wrong.
    404 Not Found - The specified URL could not be found.
    405 Method Not Allowed - You tried to access the API with an invalid method.
    500 Internal Server Error - We had a problem with our server. Please contact us.
    502, 503 Service Unavailable - We're temporarily offline for maintenance. Please try again later.

    A sample test API key is included in all the examples here, so you can test any example right away by copying the code. The sample API key has access to one company record. To test using a trial API key with access to more companies, please fill in your information at craft.co/business. To test requests using your trial or active account, replace the sample API key with your actual API key.