README

The official SDK for the OsintCat API. Typed requests and responses for every endpoint. PHP 8.1+.

composer require osintcat/osintcat-php guzzlehttp/guzzle

The SDK sends requests through any PSR-18 HTTP client; Guzzle is one.

API key

Create a key under Settings > Developer. A key is shown once; you choose its scopes and when it expires. Keep it on the server: never ship it in a browser or mobile app.

The SDK reads the key from the OSINTCAT_API_KEY environment variable when you do not pass one, and sends it in the X-API-KEY header.

Usage

<?php
require __DIR__ . '/vendor/autoload.php';

use OsintCat\OsintCatClient;
use OsintCat\Breach\Requests\SearchBreachRequest;
use OsintCat\Github\Requests\ProfileGithubRequest;

$client = new OsintCatClient(); // reads OSINTCAT_API_KEY; or new OsintCatClient(apiKey: 'cat_...')

$account = $client->account->get();
echo $account->accountInfo?->plan, PHP_EOL;

$breach = $client->breach->search(new SearchBreachRequest(['query' => 'user@example.com']));
echo $breach->resultsCount, PHP_EOL;

$profile = $client->github->profile(new ProfileGithubRequest(['username' => 'octocat']));
if ($profile->taken) {
    echo $profile->extraData?->name, PHP_EOL;
}

Methods

Method	Endpoint	What it does
`$client->account->get()`	`GET /api/user`	Account
`$client->account->modules()`	`GET /api/modules`	Modules
`$client->breach->search()`	`GET /api/breach`	Breach Lookup
`$client->breach->databaseSearch()`	`GET /api/database-search`	Database Search
`$client->breach->domain()`	`GET /api/domain`	Domain Lookup
`$client->email->lookup()`	`GET /api/email-osint`	Email OSINT
`$client->phone->lookup()`	`GET /api/phone-osint`	Phone OSINT
`$client->ip->lookup()`	`GET /api/ip`	IP Lookup
`$client->dns->resolve()`	`GET /api/dns-resolver`	DNS Resolver
`$client->minecraft->player()`	`GET /api/minecraft`	Minecraft Player
`$client->minecraft->leaks()`	`GET /api/minecraft-lookup`	Minecraft Leak Search
`$client->minecraft->profile()`	`GET /api/minecraft-lookup-v2`	Minecraft Profile
`$client->steam->profile()`	`GET /api/steam-lookup`	Steam Profile
`$client->xbox->profile()`	`GET /api/xbox-lookup`	Xbox Profile
`$client->twitch->profile()`	`GET /api/twitch`	Twitch Profile
`$client->chess->lookup()`	`GET /api/chess-osint`	Chess.com Lookup
`$client->github->profile()`	`GET /api/github-lookup`	GitHub Profile
`$client->reddit->profile()`	`GET /api/reddit`	Reddit Profile
`$client->x->profile()`	`GET /api/twitter-osint`	X (Twitter) Profile
`$client->tiktok->resolveShareLink()`	`GET /api/tiktok-resolver`	TikTok Share Link
`$client->instagram->resolveShareLink()`	`GET /api/instagram-resolver`	Instagram Share Link
`$client->vin->query()`	`GET /api/vin`	VIN Decoder
`$client->chile->person()`	`GET /api/chilean-name`	Chilean Person Search
`$client->chile->vehicle()`	`GET /api/chilean-car`	Chilean Vehicle Search
`$client->machineViewer->stats()`	`GET /api/machine_viewer/stats`	Machine Viewer statistics
`$client->machineViewer->search()`	`GET /api/machine_viewer/search`	Search machines
`$client->machineViewer->machine()`	`GET /api/machine_viewer/machines/{machine_id}/info`	Machine details
`$client->machineViewer->files()`	`GET /api/machine_viewer/machines/{machine_id}/files/treeview`	Machine files
`$client->machineViewer->file()`	`GET /api/machine_viewer/files/{file_id}/info`	File content
`$client->machineViewer->downloadFile()`	`GET /api/machine_viewer/files/{file_id}/download`	Download a file
`$client->machineViewer->downloadMachine()`	`GET /api/machine_viewer/machines/{machine_id}/download`	Download a machine

Errors

Any answer other than 2xx throws OsintCat\Exceptions\OsintcatApiException, with the status code and the body the API answered with.

use OsintCat\Exceptions\OsintcatApiException;

try {
    $client->breach->search(new SearchBreachRequest(['query' => 'user@example.com']));
} catch (OsintcatApiException $e) {
    echo $e->getCode(), ' ', json_encode($e->getBody()), PHP_EOL;
}

Status	Meaning
400	The request is not valid (a missing or wrong parameter).
401	No API key, or an unknown one.
402	Your balance does not cover the lookup.
403	The key was revoked or has expired, lacks the scope, is used from an address it is not allowed from, or your plan does not include the module.
404	Nothing was found.
429	The daily allowance is used up (`LIMIT_REACHED`, resets at 00:00 UTC), or too many requests in a short time.
424	The lookup could not be completed: a data source failed or was too slow (`X-Upstream-Status` says which).

Every error body carries error, usually message, and request_id; a server error (5xx) also error_id. Quote them to support.

Retries

The SDK does not retry on its own. A lookup that is retried after a timeout may already have been counted or charged, and a 429 LIMIT_REACHED cannot succeed before the allowance resets at 00:00 UTC. Retry yourself where it is safe for you.

Timeouts

The SDK sets no timeout of its own. Set one for every call when you create the client, or for one call:

$client = new OsintCatClient(options: ['timeout' => 60]);
$client->breach->search(new SearchBreachRequest(['query' => 'user@example.com']), ['timeout' => 120]);

Source code: github.com/OsintCatHQ/osintcat-php. Issues are welcome there.

License

MIT

osintcat / osintcat-php

Package info

Security

Statistics