> ## Documentation Index
> Fetch the complete documentation index at: https://docs.oneshotagent.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Vessel Ownership

> Look up a US-documented vessel and its managing owner by official number, IMO number or owner name.

Find a US-documented vessel and its managing owner in the US Coast Guard vessel documentation file. Search by official number, IMO number or owner-name prefix. Covers US-documented vessels only: a foreign-flag vessel is reported as not found, with that reason. No street addresses are returned.

## Authentication

Requires x402 payment in the `payment-signature` header.

## Request Body

**official\_number** `string`

Coast Guard official number, six to eight digits.

**imo** `string`

IMO ship identification number.

**owner\_name** `string`

Managing owner name prefix. 1 to 200 characters. Owner name must be valid Unicode without null characters.

**limit** `integer`

Maximum owner-search rows. From 1 to 50. Defaults to `25`.

<Snippet file="audit-context-params.mdx" />

## Response (200 OK)

Top-level envelope: `success` (boolean) and `data` (object). All fields below are nested under `data`.

**data.request\_id** `string`

Durable job ID for audit and lookup

**data.status** `string`

Job status: `completed`

**data.tool** `string`

Always `vessel_ownership`

**data.result** `object`

The answer, described under Result below

**data.evidence** `object`

Where the answer came from and when

**data.evidence.source** `string`

The public body the data comes from. Always `US Coast Guard`.

**data.evidence.source\_kind** `string`

`public` when the data comes from a public body, `commercial` otherwise

**data.evidence.retrieved\_at** `string`

When the lookup was made, as an ISO 8601 UTC time

**data.evidence.as\_of** `string | null`

When the source says the fact was last updated, or `null` when the source gives no date

## Result

Nested under `data.result`.

**data.result.found** `boolean`

Found.

**data.result.vessels** `object[]`

Vessels.

**data.result.vessels\[].observed** `object`

Observed.

**data.result.vessels\[].observed.official\_number** `string`

Official number.

**data.result.vessels\[].observed.imo** `string | null`

Imo. `null` when the source gives no value.

**data.result.vessels\[].observed.mmsi** `string | null`

Mmsi. `null` when the source gives no value.

**data.result.vessels\[].observed.name** `string | null`

Name. `null` when the source gives no value.

**data.result.vessels\[].observed.call\_sign** `string | null`

Call sign. `null` when the source gives no value.

**data.result.vessels\[].observed.flag** `string | null`

Flag. `null` when the source gives no value.

**data.result.vessels\[].observed.type** `string | null`

Type. `null` when the source gives no value.

**data.result.vessels\[].observed.self\_propelled** `boolean | null`

Self propelled. `null` when the source gives no value.

**data.result.vessels\[].observed.gross\_tonnage** `number | null`

Gross tonnage. `null` when the source gives no value.

**data.result.vessels\[].observed.itc\_gross\_tonnage** `number | null`

Itc gross tonnage. `null` when the source gives no value.

**data.result.vessels\[].observed.year\_built** `integer | null`

Year built. `null` when the source gives no value.

**data.result.vessels\[].observed.hailing\_port** `string | null`

Hailing port. `null` when the source gives no value.

**data.result.vessels\[].observed.hailing\_port\_state** `string | null`

Hailing port state. `null` when the source gives no value.

**data.result.vessels\[].observed.documentation\_status** `string | null`

Documentation status. `null` when the source gives no value.

**data.result.vessels\[].observed.documentation\_issued** `string | null`

Documentation issued. `null` when the source gives no value.

**data.result.vessels\[].observed.documentation\_expires** `string | null`

Documentation expires. `null` when the source gives no value.

**data.result.vessels\[].observed.registered\_owner** `object | null`

The managing owner the Coast Guard records. `null` when the source gives no value.

**data.result.vessels\[].observed.registered\_owner.name** `string | null`

Null for an individual: the Coast Guard withholds the name. `null` when the source gives no value.

**data.result.vessels\[].observed.registered\_owner.kind** `string | null`

The file's organisation type, or "individual". `null` when the source gives no value.

**data.result.vessels\[].observed.registered\_owner.country** `string | null`

Country. `null` when the source gives no value.

**data.result.vessels\[].observed.registered\_owner.since** `string | null`

When the party took the role, where the source gives it. `null` when the source gives no value.

**data.result.vessels\[].observed.registered\_owner.company\_id** `string | null`

The source's identifier for the party. `null` when the source gives no value.

**data.result.vessels\[].observed.manager** `object | null`

The ship manager, where a source gives one. `null` when the source gives no value.

**data.result.vessels\[].observed.manager.name** `string | null`

Null for an individual: the Coast Guard withholds the name. `null` when the source gives no value.

**data.result.vessels\[].observed.manager.kind** `string | null`

The file's organisation type, or "individual". `null` when the source gives no value.

**data.result.vessels\[].observed.manager.country** `string | null`

Country. `null` when the source gives no value.

**data.result.vessels\[].observed.manager.since** `string | null`

When the party took the role, where the source gives it. `null` when the source gives no value.

**data.result.vessels\[].observed.manager.company\_id** `string | null`

The source's identifier for the party. `null` when the source gives no value.

**data.result.vessels\[].observed.operator** `object | null`

The party that runs the vessel, where a source gives one. `null` when the source gives no value.

**data.result.vessels\[].observed.operator.name** `string | null`

Null for an individual: the Coast Guard withholds the name. `null` when the source gives no value.

**data.result.vessels\[].observed.operator.kind** `string | null`

The file's organisation type, or "individual". `null` when the source gives no value.

**data.result.vessels\[].observed.operator.country** `string | null`

Country. `null` when the source gives no value.

**data.result.vessels\[].observed.operator.since** `string | null`

When the party took the role, where the source gives it. `null` when the source gives no value.

**data.result.vessels\[].observed.operator.company\_id** `string | null`

The source's identifier for the party. `null` when the source gives no value.

**data.result.vessels\[].observed.beneficial\_owner** `object | null`

The ultimate owner, where a source gives one. `null` when the source gives no value.

**data.result.vessels\[].observed.beneficial\_owner.name** `string | null`

Null for an individual: the Coast Guard withholds the name. `null` when the source gives no value.

**data.result.vessels\[].observed.beneficial\_owner.kind** `string | null`

The file's organisation type, or "individual". `null` when the source gives no value.

**data.result.vessels\[].observed.beneficial\_owner.country** `string | null`

Country. `null` when the source gives no value.

**data.result.vessels\[].observed.beneficial\_owner.since** `string | null`

When the party took the role, where the source gives it. `null` when the source gives no value.

**data.result.vessels\[].observed.beneficial\_owner.company\_id** `string | null`

The source's identifier for the party. `null` when the source gives no value.

**data.result.vessels\[].derived** `object`

Derived.

**data.result.total** `integer`

Total.

**data.result.returned** `integer`

Returned.

**data.result.truncated** `boolean`

Truncated.

**data.result.absent\_reason** `string | null`

Why nothing matched, when coverage was available and nothing did. `null` when the source gives no value.

**data.result.coverage** `object`

Coverage.

**data.result.coverage.available** `boolean`

Available.

**data.result.coverage.as\_of** `string | null`

As of. `null` when the source gives no value.

**data.result.coverage.scope** `string`

Scope.

**data.result.coverage.reason** `string | null`

Reason. `null` when the source gives no value.

```bash cURL theme={null}
curl -X POST https://win.oneshotagent.com/v1/tools/lookup/vessel-ownership \
  -H "Content-Type: application/json" \
  -H "payment-signature: <base64 x402 payment>" \
  -d '{
    "imo": "9410179"
  }'
```

```javascript JavaScript theme={null}
const response = await fetch("https://win.oneshotagent.com/v1/tools/lookup/vessel-ownership", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "payment-signature": paymentProof,
  },
  body: JSON.stringify({
    "imo": "9410179"
  }),
});
```

```typescript SDK theme={null}
const result = await agent.tool('lookup/vessel-ownership', {
  imo: '9410179'
});
console.log(result.result);
console.log(result.evidence);
```

```json Response (200) theme={null}
{
  "success": true,
  "data": {
    "request_id": "uuid",
    "receipt_id": "rcpt_...",
    "status": "completed",
    "tool": "vessel_ownership",
    "result": {
      "found": false,
      "vessels": [],
      "total": 0,
      "returned": 0,
      "truncated": false,
      "absent_reason": "Not in the US Coast Guard vessel documentation file, which holds US-documented vessels only: a foreign-flag vessel is never found here",
      "coverage": {
        "available": true,
        "as_of": "2026-09-30T00:00:00.000Z",
        "scope": "US-documented vessels in the US Coast Guard vessel documentation file; foreign-flag vessels are not covered",
        "reason": null
      }
    },
    "evidence": {
      "source": "US Coast Guard",
      "source_kind": "public",
      "retrieved_at": "2026-11-07T00:00:00.000Z",
      "calls": [
        {
          "retrieved_at": "2026-11-07T00:00:00.000Z"
        }
      ],
      "as_of": "2026-09-30T00:00:00.000Z"
    }
  }
}
```

> [!NOTE]
>
> See [Pricing](https://docs.oneshotagent.com/pricing.md) for this tool's price. A wallet (x402) call receives it in the 402 quote before anything is charged; a call paid from prepaid credits is charged when the API accepts the request and answers `200`.

## Notes

* An empty result with coverage.available true means no match in the held monthly file, and absent\_reason says why that happens; false means no evidence either way.
* registered\_owner is the managing owner the Coast Guard records; the file names organisations only, so an individual managing owner has a null name. company\_id is the Coast Guard party identifier.
* The Coast Guard file gives no `manager`, `operator`, `beneficial_owner`, `since` or `mmsi`: those fields are null until a ship register joins this tool.
* Owner names match normalized uppercase text prefixes and find organisations only. Lists default to 25 rows, at most 50. Vessel type and documentation status keep the file's own wording.
* The file is published about monthly, early in the month it is named for, with vessel information through the day it was produced. coverage.as\_of is that date for the held release; newer documentation is absent.
* Results return inline. The finished job stays available at `/v1/requests/{request_id}`


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.