NAV
Shell JavaScript Python

Surudo API v1.0.0

Scroll down for code samples, example requests and responses. Select a language for code samples from the tabs above or the mobile navigation menu.

API for Surudo's account research tools.

Please reach out to us to get access to this API using one of the contact methods below:

Email: Surudo Support

Web: Surudo Website

Authentication

Code Samples

# 1) Obtain token
curl -X POST \
     -H "Content-Type: application/json" \
     -d '{"username":"testuser@example.com","password":"testpassword"}' \
     https://api.surudo.ai/v1/users/token

# Example response:
# {
#   "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
#   "token_type": "bearer"
# }

# 2) Use the token (replace ACCESS_TOKEN with the returned token)
curl -X GET \
     -H "Authorization: Bearer ACCESS_TOKEN" \
     https://api.surudo.ai/v1/some/protected    

// 1) Obtain token
fetch('https://api.surudo.ai/v1/users/token', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    username: 'testuser@example.com',
    password: 'testpassword'
  })
})
  .then(res => res.json())
  .then(data => {
    const token = data.access_token;
    console.log('Access Token:', token);

    // 2) Use the token in the Authorization header
    return fetch('https://api.surudo.ai/v1/some/protected', {
      headers: {
        'Authorization': `Bearer ${token}`
      }
    });
  })
  .then(res => res.json())
  .then(json => {
    console.log('Protected endpoint response:', json);
  })
  .catch(err => {
    console.error('Error:', err);
  });

import requests

base_url = "https://api.surudo.ai/v1"

# 1) Obtain token
token_resp = requests.post(f"{base_url}/users/token", json={
    "username": "testuser@example.com",
    "password": "testpassword"
})
token_data = token_resp.json()
access_token = token_data.get("access_token")

if not access_token:
    print("Failed to obtain token:", token_resp.status_code, token_data)
    exit(1)

print("Access Token:", access_token)

# 2) Use the token in subsequent requests
headers = {"Authorization": f"Bearer {access_token}"}
resp = requests.get(f"{base_url}/some/protected", headers=headers)

print("Protected endpoint status:", resp.status_code)
print("Protected endpoint data:", resp.json())

The Surudo API uses OAuth2 with a password flow to authenticate and obtain an access token.
Once you have the token, include it in the Authorization header with the value Bearer <ACCESS_TOKEN> in subsequent requests.

Scope Scope Description
none not currently required

How It Works

  1. POST your username and password to /users/token.
  2. If the credentials are valid, the server responds with a JSON payload containing an access_token and token_type.
  3. Pass this token in the Authorization header for all future requests, for example:
    Authorization: Bearer <ACCESS_TOKEN>

Credits

The Surudo API uses a credit system to track usage.

The system is simple: each call to one of the Companies endpoints uses a single credit.

The cost of each credit is set by your contract with Surudo. For a copy of this contract or any other information about this credit system, please contact Surudo Support.

credits

Code Samples

curl -X GET \
     -H "Authorization: Bearer ACCESS_TOKEN" \
     https://api.surudo.ai/v1/credits?email=USER_EMAIL_ADDRESS    

  const token = 'ACCESS_TOKEN';
  const user_email_address = 'exampleuser@example.com';
  fetch('https://api.surudo.ai/v1/credits?email=${user_email_address}', {
    method: 'GET',
    headers: { 'Content-Type': 'application/json',
           'Authorization': `Bearer ${token}`
    }
  })
  .then(res => res.json())
  .then(json => {
    console.log('Endpoint response:', json);
  })
  .catch(err => {
    console.error('Error:', err);
  });

import requests

user_email_address = "exampleuser@example.com"
url = f"https://api.surudo.ai/v1/credits?email={user_email_address}"
headers = {"Authorization": f"Bearer {access_token}"}
resp = requests.get(url, headers=headers)

print("Endpoint status:", resp.status_code)
print("Endpoint data:", resp.json())

GET /credits

Get User Credit Usage

URL parameter

?email=exampleuser@example.com

Parameters

Name In Type Required Description
email query string [string] true none

Example responses

200 Response

{
  "credit_usage": "integer"
}

Responses

Status Meaning Description Schema
200 OK Successful Response User
404 [User not found] HTTP Exception HTTPException

Users

get_user_by_email

Code samples

# Replace ACCESS_TOKEN with your actual token
curl -X GET \
     -H "Authorization: Bearer ACCESS_TOKEN" \
     "https://api.surudo.ai/v1/users/get_user_by_email?email=exampleuser@example.com"

// Replace ACCESS_TOKEN with your actual token
const token = 'ACCESS_TOKEN';
fetch('https://api.surudo.ai/v1/users/get_user_by_email?email=exampleuser@example.com', {
  method: 'GET',
  headers: {
    'Authorization': `Bearer ${token}`
  }
})
  .then(response => {
    console.log('Status:', response.status);
    return response.json();
  })
  .then(data => {
    console.log('Get user by email Response:', data);
  })
  .catch(error => console.error('Error:', error));


headers = {"Authorization": f"Bearer {access_token}"}
url = "https://api.surudo.ai/v1/users/get_user_by_email?email=exampleuser@example.com"
response = requests.get(url, headers=headers, params=params)
print("Get user by email Response:", response.status_code, response.json())

GET /users/get_user_by_email

Get User Profile Information

URL parameter

?email=exampleuser@example.com

Parameters

Name In Type Required Description
email query string [string] true none

Example responses

200 Response

{
  "name": "string"
  "email": "string"
  "date_created": "string"
}

Responses

Status Meaning Description Schema
200 OK Successful Response User
404 [User not found] HTTP Exception HTTPException

subscriptions

Code samples

# Replace ACCESS_TOKEN with your actual token
curl -X GET \
     -H "Authorization: Bearer ACCESS_TOKEN" \
     "https://api.surudo.ai/v1/users/subscriptions?email=exampleuser@example.com"

// Replace ACCESS_TOKEN with your actual token
const token = 'ACCESS_TOKEN';
fetch('https://api.surudo.ai/v1/users/subscriptions?email=exampleuser@example.com', {
  method: 'GET',
  headers: {
    'Authorization': `Bearer ${token}`
  }
})
  .then(response => {
    console.log('Status:', response.status);
    return response.json();
  })
  .then(data => {
    console.log('Get user subscriptions Response:', data);
  })
  .catch(error => console.error('Error:', error));

headers = {"Authorization": f"Bearer {access_token}"}
url = "https://api.surudo.ai/v1/users/subscriptions?email=exampleuser@example.com"
response = requests.get(url, headers=headers, params=params)
print("Get user by email Response:", response.status_code, response.json())

GET /users/subscriptions

Get User Subscription Information

URL parameter

?email=exampleuser@example.com

Parameters

Name In Type Required Description
email query string [string] true none

Example responses

200 Response

{
  "subscriptions": "list"
}

Responses

Status Meaning Description Schema
200 OK Successful Response User
404 [User not found] HTTP Exception HTTPException

Companies

company_website

Code samples

# You can also use wget
curl -X POST \
  -H 'Accept: application/json' \
  -H 'Content-type: application/json' \
  -H 'Authorization: Bearer {access-token}' \
  -d '{ "domain": "https://www.salesforce.com", "number_results": "100" }' \
  https://api.surudo.ai/v1/company_website

const url = "https://api.surudo.ai/v1/company_website";

// Replace {access-token} with your actual token
const accessToken = "{access-token}";

fetch(url, {
  method: "POST",
  headers: {
    "Accept": "application/json",
    "Authorization": `Bearer ${accessToken}`,
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    domain: "https://www.salesforce.com",
    number_results: "100"
  })
})
  .then(response => {
    console.log("Status:", response.status);
    return response.json();
  })
  .then(data => {
    console.log("Response data:", data);
  })
  .catch(error => {
    console.error("Error:", error);
  });


import requests

url = "https://api.surudo.ai/v1/company_website"

# Replace {access-token} with your actual token
access_token = "{access-token}"

headers = {
    "Accept": "application/json",
    "Authorization": f"Bearer {access_token}"
}

payload = {
    "domain": "https://www.salesforce.com",
    "number_results": "100"
}

response = requests.post(url, headers=headers, json=payload)

print("Status code:", response.status_code)
print("Response data:", response.json())

POST /company_website

Get Latest Company Website

Because some pages have a significant number of subpages, this endpoint provides streaming output.

Parameters

Name In Type Required Description
domain payload [string] true Domain of company
number_results payload [int] false Number of pages to include in response

Example responses

200 Response

{
"pages": [{
    "page_url": "string",
    "page_html": "string",
    "page_text": "string"
}]
"collected_date": "string"
}

Responses

Status Meaning Description Schema
200 OK Successful Response Inline
404 [Company not found] HTTP Exception HTTPException

Response Schema

company_embedding

Code samples

# You can also use wget
curl -X POST \
  -H 'Accept: application/json' \
  -H 'Content-type: application/json' \
  -H 'Authorization: Bearer {access-token}' \
  -d '{ "domain": "https://www.salesforce.com" }' \
  https://api.surudo.ai/v1/company_embedding


const url = "https://api.surudo.ai/v1/company_embedding";

// Replace {access-token} with your actual token
const accessToken = "{access-token}";

fetch(url, {
  method: "POST",
  headers: {
    "Accept": "application/json",
    "Authorization": `Bearer ${accessToken}`,
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    domain: "https://www.salesforce.com"
  })
})
  .then(response => {
    console.log("Status:", response.status);
    return response.json();
  })
  .then(data => {
    console.log("Response data:", data);
  })
  .catch(error => {
    console.error("Error:", error);
  });


import requests

url = "https://api.surudo.ai/v1/company_embedding"

# Replace {access-token} with your actual token
access_token = "{access-token}"

headers = {
    "Accept": "application/json",
    "Authorization": f"Bearer {access_token}"
}

payload = {
    "domain": "https://www.salesforce.com",
}

response = requests.post(url, headers=headers, json=payload)

print("Status code:", response.status_code)
print("Response data:", response.json())

POST /company_embedding

Get Latest Company Embedding

Parameters

Name In Type Required Description
domain payload [string] true Domain of company

Example responses

200 Response

{
"embedding": ["float"],
"generated_date": "string",
"embedding_model": "string"
}

Responses

Status Meaning Description Schema
200 OK Successful Response Inline
404 [Company not found] HTTP Exception HTTPException

Response Schema

company_pages

Code samples

# You can also use wget
curl -X POST \
  -H 'Accept: application/json' \
  -H 'Content-type: application/json' \
  -H 'Authorization: Bearer {access-token}' \
  -d '{ "domain": "https://www.salesforce.com" }' \
  https://api.surudo.ai/v1/company_pages

const url = "https://api.surudo.ai/v1/company_pages";

// Replace {access-token} with your actual token
const accessToken = "{access-token}";

fetch(url, {
  method: "POST",
  headers: {
    "Accept": "application/json",
    "Authorization": `Bearer ${accessToken}`,
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    domain: "https://www.salesforce.com"
  })
})
  .then(response => {
    console.log("Status:", response.status);
    return response.json();
  })
  .then(data => {
    console.log("Response data:", data);
  })
  .catch(error => {
    console.error("Error:", error);
  });


import requests

url = "https://api.surudo.ai/v1/company_pages"

# Replace {access-token} with your actual token
access_token = "{access-token}"

headers = {
    "Accept": "application/json",
    "Authorization": f"Bearer {access_token}"
}

payload = {
    "domain": "https://www.salesforce.com",
    "number_results": "100"
}

response = requests.post(url, headers=headers, json=payload)

print("Status code:", response.status_code)
print("Response data:", response.json())

POST /company_pages

Get Latest Company Pages and Meta-Data

Parameters

Name In Type Required Description
domain payload [string] true Domain of company

Example responses

200 Response

{
"number_of_pages": "integer",
"collected_date": "string",
"page_urls": ["string"]
}

Responses

Status Meaning Description Schema
200 OK Successful Response Inline
404 [Company not found] HTTP Exception HTTPException

Response Schema

Shell JavaScript Python