Altss developer reference.
Read public catalogs, documents and bounded profile summaries with Python, JavaScript, Go, the command line or HTTP. Search published profiles with REST, MCP, NLWeb or A2A. Connect documentation MCP or install a focused research skill.
Search sandbox fixtures
Expect HTTP 200 and two fictional results. Their example.com URLs are fixture citations, not real companies. Sandbox requests never query production records.
curl --fail-with-body --silent --show-error "https://altss.com/api/v1/sandbox/public/profiles?query=Example&limit=2"Read a page of public matches
Expect HTTP 200 with a bounded results array. Cite each returned canonical profile URL; missing facts remain unknown. No account or token is required.
curl --fail-with-body --silent --show-error \
"https://altss.com/api/v1/public/profiles?query=Daimler%20Truck&limit=2"Paid Console delivery and data rights
Console connection guide
The separate Altss Console publishes authenticated REST and MCP interfaces and a catalog for bounded SEC financial research using public issuer filings. Follow its connection guide and current tool catalog for account eligibility, credential setup, scope, quotes and funding requirements. This does not grant private-company dossiers, contact enrichment or unrestricted graph access.
Current Console tools
Protected Console OpenAPI
Actual Console REST, MCP and custom grant contracts. Separate credentials, approval and funding checks apply.
Console pricing and funding
Console, API and MCP Data License
Purchased scoped access, customer and agent authority, permitted embedding and source restrictions. Documentation is not an entitlement or an announcement that a tool is live.
Privacy and correction requests
Request access, correction, restriction, erasure or review without payment or an account.
Start with a public read
Public profile search, individual summaries, the bounded batch reader and published catalogs require no account, key, token or payment. Use the fictional sandbox to test your integration. Catalogs describe fields, commercial terms and manually reviewed tasks; the public reader returns limited published profile summaries.
Anonymous access, sandbox and permissions
Run the public reader walkthrough
Executable search and batch examples, expected results and retry guidance.
Public profile reader OpenAPI
Public search, summary and batch operations, production and sandbox servers, and machine-readable anonymous permissions.
Fictional sandbox directory
Test without credentials or production data queries.
Versioning and deprecation
Breaking response-shape changes require a new URL major version. Within v1, existing fields retain their types and meaning. Changes that would invalidate a response against the v1 contract belong in a new major version. Catalog values and their own version or update dates can change within that contract without a transport-version change.
No published public descriptive endpoint is currently deprecated or scheduled for removal. Before retiring a supported endpoint, publish a migration notice and replacement, signal deprecation with the Deprecation header (RFC 9745), and use Sunset (RFC 8594) only when an actual withdrawal date has been announced. Supported aliases are not silently redirected to a different major version.
JavaScript SDK and command-line client
The Altss public client reads named catalogs, JSON Schemas, Markdown documents and bounded public profile summaries. Its sandbox option selects fictional profile fixtures. It includes TypeScript declarations and requires Node.js 22 or newer. Each read makes one GET to an allowlisted public Altss resource, with a bounded timeout, no credentials and no automatic retries.
Install from npm
Install version 0.2.0 of altss-public-client from the public npm registry. It includes the JavaScript client, TypeScript declarations and local CLI, with no runtime dependencies or installation scripts.
npm install --ignore-scripts --save-exact altss-public-client@0.2.0Install from source
Use the matching tagged GitHub release if you prefer a source installation. Choose one installation method for your project.
npm install --ignore-scripts github:Altssdata/public-client#v0.2.0Read with the JavaScript client
The same import works with TypeScript. A conditional 304 returns data: null; reuse the representation associated with the ETag you supplied.
import { AltssPublicClient } from "altss-public-client";
const client = new AltssPublicClient({ timeoutMs: 10000 });
const response = await client.getCatalog("data");
if (response.status === 200) console.log(response.data);Read from the command line
After installation, run the local CLI to read public resources. Commands print a JSON envelope; help and resource enumeration work offline.
npx --no-install altss-public catalog data
npx --no-install altss-public schema company
npx --no-install altss-public document pricing
npx --no-install altss-public resourcesSearch with the JavaScript SDK
Only public profile summaries are returned. Use sandbox: true for fictional fixtures, with no production data queries.
const page = await client.searchProfiles("Daimler Truck", { limit: 2 });
if (page.status === 200) console.log(page.data.results);
const sandbox = new AltssPublicClient({ sandbox: true });
const sample = await sandbox.getProfile("example-capital-01");Python SDK
The Python client requires Python 3.11 or newer and uses the standard library, with no runtime dependencies. It reads catalogs, schemas, Markdown documents and bounded published profile summaries through anonymous GET requests to the fixed public Altss origin. It rejects redirects, caps responses at 4 MiB and makes no automatic retries. Its socket timeout is not a hard process deadline: operating-system DNS resolution and slow response headers can exceed that budget.
Install from PyPI
Install the published 0.1.0 wheel. Python, JavaScript and Go have separate release versions; use the version specified for each language.
python -m pip install --only-binary=:all: --no-deps altss-public-client==0.1.0Read with Python
The data catalog describes public fields. Set sandbox=True to read fictional profile fixtures; the sandbox option affects profile methods only. A conditional catalog or document response with status 304 has data=None.
from altss_public import AltssPublicClient
client = AltssPublicClient(timeout=10)
response = client.get_catalog("data")
print(response.data)
sandbox = AltssPublicClient(sandbox=True)
fixture = sandbox.get_profile("example-capital-01")
print(fixture.data)Go SDK
The Go module uses the standard library and the same fixed public Altss origin, anonymous GET requests, redirect rejection, response-size limits and deadlines. SearchProfiles, Profile, Catalog, Schema, Document and OpenAPI read public resources. Options{Sandbox: true} selects fictional fixtures for profile methods. It has no Product login, account or write methods.
Install the Go module
Use the module's versioned subdirectory tag. It is distributed through GitHub and the Go module proxy.
go get github.com/Altssdata/public-client/go@v0.1.0Read with Go
Check errors and the HTTP status before using the response. Missing records and temporary failures remain errors.
package main
import (
"context"
"log"
"github.com/Altssdata/public-client/go"
)
func main() {
client, err := altsspublic.New(altsspublic.Options{})
if err != nil { log.Fatal(err) }
result, err := client.SearchProfiles(context.Background(), "Daimler Truck", 2, "")
if err != nil { log.Fatal(err) }
log.Print(result.Data)
}Client source and releases
altss-public-client on npm
Published JavaScript client, TypeScript declarations and command-line package.
altss-public-client on PyPI
Published Python package, typed public reads and fictional sandbox profile fixtures.
Altss public Go SDK on Go Packages
Published Go module documentation, exported methods and version history.
Altss public client repository
Python, JavaScript and Go source, conditional reads, response limits, error handling and tests.
Version 0.2.0 release
Tagged source and the packaged JavaScript SDK and CLI.
Python version 0.1.0 release
Tagged Python source and the wheel and source distribution published on PyPI.
Report a client issue
Include the resource name and observed behavior. Omit credentials and private records.
Read the data catalog
This request returns JSON field descriptions. Use the versioned base URL for new integrations.
curl --fail-with-body --silent --show-error \
--header "Accept: application/json" \
"https://altss.com/api/v1/data-catalog.json"Public HTTP resources
First-party machine API index
Anonymous public and protected Console operations, with explicit servers and security requirements. Use the public-only specification for anonymous SDKs.
Public-only OpenAPI
Existing anonymous operation IDs, response schemas, examples, supported methods and versioning policy.
Data catalog
Entity and field definitions, availability and access labels.
Task catalog
Inputs, outputs and maximum scope of manually reviewed tasks.
Commercial catalog
Current public products, prices, terms and purchase routes.
API discovery catalog
The actual resource URLs and their specification, in RFC 9727 linkset format.
Use the catalog in JavaScript
Native fetch works in current browsers and Node.js. Check the status before parsing; keep timeouts bounded.
const response = await fetch(
"https://altss.com/api/v1/data-catalog.json",
{ headers: { Accept: "application/json" }, signal: AbortSignal.timeout(10000) }
);
if (!response.ok) throw new Error("Altss HTTP " + response.status);
const catalog = await response.json();
console.log(catalog.entities.map(entity => entity.label));Handle responses correctly
- For catalogs and schema documents, retain the ETag from a successful response and send it in If-None-Match on the next request. A 304 has no body; reuse your stored representation. Public profile reads use private/no-store responses without conditional 304 behavior.
- Read current Cache-Control and Retry-After headers. Back off after temporary failures. Catalogs publish no numeric request allowance; public profile interfaces have the separate instance budgets below.
- A catalog's update date describes that document. Field availability and source dates remain specific to each underlying record.
- The original root catalog URLs remain supported. Use /api/v1 for versioned catalogs, schemas and bounded public profile reads. Consult the OpenAPI document before relying on an operation.
Inspect JSON Schemas
Each link returns a schema document, with its permitted fields and evidence structure.
Request a page as Markdown
The canonical URL supports explicit Accept negotiation. Recognized public-reading agents also receive Markdown when Accept is absent or contains only permitted wildcards. Explicit HTML requests stay HTML. The .md alternate is also available, and citations should retain the canonical HTML URL.
curl --fail-with-body --silent --show-error \
--header "Accept: text/markdown" \
"https://altss.com/pricing"Read and cite published material
Batch routes
POST /api/v1/public/batch reads one to five unique public slugs. The original /api/v1/public/profile-batch remains supported with identical input, results, limits and shared replay state. The sandbox offers both paths below /api/v1/sandbox. Both operations are formally defined in the public OpenAPI.
Try the public API sandbox
Use https://altss.com/api/v1/sandbox for deterministic fictional profile fixtures. It has the same search, individual read and read-only batch contracts as the public API, with separate server-instance request budgets and replay caches. Sandbox requests never query production records. Responses identify Altss-Environment: sandbox. Fixture URLs use example.com and are not real company citations. No account or credentials are needed.
Search published profiles with REST
The public API searches organization names and reads limited published profile summaries with canonical citations. No account or token is required. It uses the same public records as the profile pages and public-profile MCP; it does not expose subscription data or application operations.
Search parameters and pagination
Use query (2–120 characters) and limit (1–5). Follow pagination.nextCursor with the same query. Pagination covers at most ten matches; it is not a full-inventory export. A changed result window returns STALE_CURSOR: restart the query.
Read one public summary
Known aliases resolve to the canonical profile URL. A missing slug returns 404; an upstream failure returns 503. Missing facts remain unknown. pageUpdatedAt is page modification, not field verification.
curl --fail-with-body --silent --show-error \
"https://altss.com/api/v1/public/profiles/daimler-truck-ag"Read a bounded profile batch
POST reads one to five unique, explicit slugs. Check each item's status: 200, 404 or 503. The optional Idempotency-Key coalesces identical requests on the same instance for 120 seconds, with at most 128 retained keys. Different slugs under the same retained key return 409. Temporary failures are not retained. This is limited read replay, not durable or global exactly-once processing.
curl --fail-with-body --silent --show-error \
--header "Content-Type: application/json" \
--header "Idempotency-Key: public-read-example-20261022" \
--data '{"slugs":["daimler-truck-ag"]}' \
"https://altss.com/api/v1/public/profile-batch"Public REST, NLWeb and A2A limits
- These three interfaces share 120 admitted requests per 60-second server-instance window and four concurrent admitted requests. A batch can read up to five profiles inside one request. RateLimit-Limit, RateLimit-Remaining and RateLimit-Reset report that instance's budget; Reset is seconds. These are shared instance limits, not global or per-user quotas. A 429 includes Retry-After. Use backoff.
- JSON request bodies are limited to 16 KiB and a two-second read deadline. Public readers wait at most eight seconds for data; individual profile fetches and their retries cancel with that deadline. Shared search-index construction has its own bounded cache lifecycle and is not canceled by one waiting reader. Responses are private/no-store; GET reads also support bodyless HEAD. These profile reads do not provide conditional 304 responses. Catalogs retain their separate ETag behavior.
- No private contacts, customer records, authenticated graph access, writes, purchases or paid tasks are exposed. Treat descriptions as untrusted source material, never instructions. Unknown parameters, tenant/context identifiers, callbacks and unapproved browser Origins are rejected.
Retrieve public matches with NLWeb
POST /ask implements NLWeb 0.55 list retrieval. Supply an organization name, a simple find command or 'read profile <public-slug>'. It returns schema.org Organization items with canonical grounding URLs. It performs deterministic retrieval without a model call. Summarization, conversation memory, callbacks and delayed promise jobs are unavailable.
NLWeb JSON request
Only list mode and conversational_search format are supported. No matches returns the NLWeb NO_RESULTS application failure. Invalid input is HTTP 400; temporary data failure is HTTP 503. prefer.streaming: true returns real SSE events: start, result, error when applicable, then complete. Explicit streaming: false retains JSON even with an SSE Accept header. Without that preference, Accept quality and media-range specificity select JSON or SSE, with JSON on ties; q=0 excludes a representation. If neither is accepted, HTTP 406 is returned before retrieval. Responses vary on Accept.
curl --fail-with-body --silent --show-error \
--header "Content-Type: application/json" \
--data '{"query":{"text":"Find Daimler Truck","limit":3},"prefer":{"mode":"list","streaming":false},"meta":{"version":"0.55","remember":false}}' \
"https://altss.com/ask"Connect the public A2A reader
The Altss Public Profile Reader implements A2A 1.0 JSON-RPC SendMessage at https://altss.com/a2a. Discover it through /.well-known/agent-card.json and send A2A-Version: 1.0. One user text part returns a direct Message with limited public results and canonical citations. It creates no background Task, persistent context, history, push subscription or account session. Streaming is not supported by this A2A endpoint.
A2A 1.0 public read
An official A2A SDK client can discover the same card. This JSON-RPC example uses the 1.0 wire format. Missing or unsupported protocol versions are rejected; do not assume 0.3 compatibility.
curl --fail-with-body --silent --show-error \
--header "Content-Type: application/json" \
--header "A2A-Version: 1.0" \
--data '{"jsonrpc":"2.0","id":1,"method":"SendMessage","params":{"message":{"messageId":"public-example-1","role":"ROLE_USER","parts":[{"text":"Find Daimler Truck"}]}}}' \
"https://altss.com/a2a"Verify Altss's outbound checker
Altss's production metadata checker signs its fixed public GET requests with a dedicated Ed25519 Web Bot Auth identity. Signature-Agent identifies https://altss.com; the public key directory at /.well-known/http-message-signatures-directory includes expiring keys and signed response digests. This identifies Altss's own checker, not visiting agents or customer accounts. It does not confer a vendor's verified-bot registration or a private-data entitlement.
Check public integration metadata in the background
Before connecting an agent, queue a durable check of Altss's OpenAPI document, data catalog, official public-profile MCP Registry record and published MCP npm package. The job reads those four fixed public metadata documents and reports availability and expected document shape. It accepts no URLs or profile data and never reads the authenticated application. A healthy result is a point-in-time integration check, not a security certification.
Start a public-interface check
This HTTP operation is separate from the GET-only SDKs. A successful POST returns 202, a job ID, a statusUrl and a Location header. Acceptance does not mean the checks passed.
curl --fail-with-body --silent --show-error --include \
--request POST --header "Content-Type: application/json" \
--data '{"kind":"public-interface-check"}' \
"https://altss.com/api/v1/public/check-jobs"Poll the returned status URL
Set STATUS_URL to the exact statusUrl from the 202 response. Wait at least Retry-After seconds between polls. HEAD returns the same status and headers without a body.
curl --fail-with-body --silent --show-error \
--header "Accept: application/json" "$STATUS_URL"Interpret job status and limits
- Status is queued, running, completed or failed. A completed result contains four resource codes and a healthy or degraded outcome. Check every resource: HTTP_ERROR, INVALID_DOCUMENT, TOO_LARGE and UNAVAILABLE describe a failed probe; they never include provider bodies or credentials.
- Status is private/no-store and expires fifteen minutes after job creation; a known expired job returns 410. Unknown or unrelated workflows return 404. Hosting-plan workflow retention is separate from this public status lifetime.
- The service reuses a recent check within a deployment's five-minute window once its durable ownership hook is registered. Simultaneous starts can create extra runs that adopt the owner's result without repeating its probes. A reused check may already be completed; poll for its actual state.
- Submission admission is ten requests per minute per instance, in addition to shared public-reader limits of 120 requests per minute and four concurrent requests per instance. These are shared instance budgets, not global or per-user quotas. A 429 includes Retry-After. A 503 can follow an accepted start whose acknowledgement was lost; back off before retrying.
- Each job reads at most two resources concurrently. Probes have ten-second deadlines, reject redirects and stop at 512 KiB per response. Inputs use the existing sixteen-KiB body limit and two-second read deadline. No private records, accounts, payments, paid tasks or arbitrary network targets are accepted.
Search and read public profiles over MCP
Altss Public Profiles provides bounded name search, individual reads and batches of up to five published organization profiles with canonical citations. Connect https://altss.com/mcp using a client that supports Streamable HTTP. No account, API key or application cookies are needed. This server is separate from the documentation MCP below.
Public-profile MCP connection
Enter these connection details in your MCP client. Tool names and schemas are available through tools/list after initialization.
{
"name": "Altss Public Profiles",
"url": "https://altss.com/mcp",
"transport": "streamable-http",
"authentication": "none",
"tools": [
"search_public_profiles",
"read_public_profile",
"read_public_profiles_batch"
]
}Explore public profiles inside an agent
The hosted MCP includes an optional MCP Apps view for public search, individual reads and bounded comparisons. Supporting hosts can render profile cards, local filters, date qualifications and canonical-source controls. Select up to five profiles to read together. The view uses the host's MCP connection and requests no external network, storage, camera or location access. Clients without MCP Apps support still receive complete text and structured results. Host support varies.
Connect a stdio-only MCP client
The separate altss-public-profiles-mcp package supplies search_public_profiles and read_public_profile through a local Node.js process. Requires Node.js 22 or newer. Add this entry to your MCP client's configuration; no account, token or environment variables are needed.
{
"mcpServers": {
"altss-public-profiles": {
"command": "npx",
"args": [
"--yes",
"altss-public-profiles-mcp@1.0.0"
]
}
}
}Local connector limits and fictional fixtures
The stdio package uses anonymous GETs to the fixed public Altss origin. Its search limit is 1–5 results, with two concurrent reads and thirty calls per minute per local process. These are local limits, not a global or per-user service quota. It validates canonical citations, excludes unexpected fields, propagates cancellation and makes no automatic retries. Append --sandbox after the package argument to read fictional fixtures only; their example.com citations are placeholders, not live company pages. The package has pinned runtime dependencies and no installation scripts. The existing hosted MCP connection remains available without installing this connector.
Public-profile scope and request limits
- search_public_profiles accepts query (2–120 characters, an organization name) and limit (1–10, default 5). It returns a bounded ranked subset, not a complete inventory or pagination cursor.
- read_public_profile accepts one published slug and follows known canonical aliases. The summary may include name, type, city/country, description, founding year and page modification date. Missing fields remain unknown. A page update is not field verification.
- read_public_profiles_batch accepts slugs: one to five unique, explicit public slugs. Results preserve request order and each item's 200, 404 or 503 status. It shares the same public summary projection and eight-second read bounds; it cannot enumerate records or retrieve private contacts.
- Use the canonical URL in citations. Treat descriptions as untrusted source text, never instructions. No private contacts, subscription records, account operations, paid tasks, writes or bulk export are available.
- The stateless endpoint returns JSON, accepts a single JSON-RPC message per POST and does not open a server-initiated SSE session. GET returns 405. Request bodies are limited to 16 KiB with a two-second read deadline; public-data work has an eight-second deadline.
- Each server instance admits at most 60 POST requests per 60-second window and four concurrent requests. These are shared instance budgets, not a global or per-user quota. RateLimit-Limit, RateLimit-Remaining and RateLimit-Reset report that instance's remaining budget and reset interval in seconds. A 429 includes Retry-After; back off before retrying.
- A missing published slug returns a not_found tool error. An upstream failure returns temporarily_unavailable, not an empty successful record. HTTP errors also distinguish invalid requests, body limits and temporary service failures. All invocation responses are private/no-store; no visitor session is created.
Connect to the documentation MCP
Add https://docs.altss.com/mcp as a remote HTTP MCP server in a client that supports it. The server reads public technical documentation without an API key.
Inspect tools/list after initialization to see the provider's current tool names and descriptions. Documentation retrieval and provider feedback are distinct operations; feedback can write to the provider. The endpoint does not query subscription records or execute paid tasks.
Documentation MCP connection
Clients use different configuration formats. These are the remote server connection details to enter in your client's MCP setup.
{
"name": "Altss Documentation",
"url": "https://docs.altss.com/mcp",
"transport": "streamable-http",
"authentication": "none for public documentation"
}Install an Altss skill
This installs the public research instructions into the current Codex project. Choose a focused skill below for profile verification or listing preparation.
npx --yes skills@1.7.4 add Altssdata/skills \
--skill altss-public-research --agent codex --yesChoose the workflow
Public research
Read the right public source and return evidence with canonical citations.
Profile verification
Check identity, source dates, contradictions and unknowns before proposing a correction.
Listing preparation
Prepare a Basic, Enhanced or correction email for manual review.
All three skills on skills.sh
Console protocol verification client
The Altss Console protocol verification client is an operator test client, not a supported SDK or an automatic authorization path. Its fixed public client metadata contains no secret and grants no access. Any verification still requires normal Console sign-in, explicit human approval and the protocol's security controls. The website does not receive its loopback authorization callback.