API Reference

Access Mashinii ethical scoring and company data through our REST API. Integrate value-based analysis, company ratings, and search directly into your applications.

Base URL:https://api.mashinii.com

Authentication

The External Data API uses API key authentication. Include your key in the Authorization header:

Authorization: Bearer YOUR_API_KEY

API keys are issued as part of a data-licensing agreement. Public endpoints (marked as Public) do not require authentication.

Scores

Retrieve ethical scores and historical data. All endpoints require an API key passed via the Authorization header.

GET/v1/score/{ticker}API Key

Get Score

Returns the current ethical score breakdown for a given ticker, including all 11 value dimensions and the overall rating.

Parameters

tickerstringrequiredCompany ticker (e.g. TSLA.US, BP.LSE)

Request

curl -X GET \
  "https://api.mashinii.com/v1/score/TSLA.US" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

{
  "ticker": "TSLA.US",
  "name": "Tesla Inc",
  "rating": "Mixed",
  "values": [
    { "value": "Animal Welfare", "score": -42 },
    { "value": "Environmental Impact", "score": 18 },
    ...
  ]
}

GET/v1/scoresAPI Key

Batch Scores

Returns current scores for multiple tickers in a single request.

Parameters

tickersstringrequiredComma-separated list of tickers (e.g. TSLA.US,AAPL.US,BP.LSE)

Request

curl -X GET \
  "https://api.mashinii.com/v1/scores?tickers=TSLA.US,AAPL.US,BP.LSE" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

[
  { "ticker": "TSLA.US", "rating": "Mixed", "values": [...] },
  { "ticker": "AAPL.US", "rating": "Mixed", "values": [...] },
  { "ticker": "BP.LSE", "rating": "Mixed", "values": [...] }
]

Lookup

Find tickers, search companies, and retrieve summaries. These endpoints are public and do not require authentication.

GET/assets/universePublic

Universe

Returns the full list of companies in our coverage universe with ticker and name.

Request

curl -X GET "https://api.mashinii.com/assets/universe"

Response

[
  { "ticker": "AAPL.US", "name": "Apple Inc" },
  { "ticker": "TSLA.US", "name": "Tesla Inc" },
  ...
]

POST/assets/searchPublic

Search

Semantic search across all companies. Supports natural language queries like 'oil companies' or 'tech companies in Europe'.

Parameters

querystringrequiredSearch query

limitnumberMax results (default 20)

min_scorenumberMinimum relevance score 0-1 (default 0.5)

Request

curl -X POST "https://api.mashinii.com/assets/search" \
  -H "Content-Type: application/json" \
  -d '{"query": "electric vehicle companies", "limit": 10}'

Response

[
  { "ticker": "TSLA.US", "name": "Tesla Inc" },
  { "ticker": "RIVN.US", "name": "Rivian Automotive Inc" },
  ...
]

GET/assets/summary/{ticker}Public

Company Summary

Returns the AI-generated ethical summary, overall rating, and company name for a given ticker.

Parameters

tickerstringrequiredCompany ticker (e.g. TSLA.US)

Request

curl -X GET "https://api.mashinii.com/assets/summary/TSLA.US"

Response

{
  "ticker": "TSLA.US",
  "name": "Tesla Inc",
  "rating": "Mixed",
  "summary": "Tesla presents a mixed ethical record..."
}

GET/values/values-publicPublic

Value Dimensions

Returns all 11 value dimensions with names and descriptions.

Request

curl -X GET "https://api.mashinii.com/values/values-public"

Response

[
  {
    "value_name": "Animal Welfare",
    "description": "Evaluates treatment of animals..."
  },
  ...
]

GET/assets/rankings/{value_name}/{direction}Public

Rankings

Returns the top 10 best or worst scoring companies for a specific value dimension.

Parameters

value_namestringrequiredValue dimension name (e.g. Environmental Impact)

directionstringrequired'best' for highest scores, 'worst' for lowest

Request

curl -X GET "https://api.mashinii.com/assets/rankings/Environmental%20Impact/best"

Response

[
  { "ticker": "ADBE.US", "name": "Adobe Systems", "score": 65 },
  ...
]

Access

API access is provisioned under a data-licensing agreement. Rate limits, endpoint scope, and delivery terms are defined in the agreement. Contact us via /research.

Error Codes

Code	Meaning
200	Success
400	Bad request. Check your parameters.
401	Unauthorized. Invalid or missing API key.
403	Forbidden. Insufficient permissions for this endpoint.
404	Not found. The requested ticker or resource does not exist.
429	Rate limit exceeded. Limits are defined in your licensing agreement.
500	Server error. Try again later.