Oversas

IPFS public HTTP Gateway & RPC API

Two things to know before you start:

• Only ipfs.oversas.org accepts writes. On oversas.org, www.oversas.org, drive.oversas.org and docs.oversas.org the gateway is read only.
• Added content is not pinned. It is served while it remains in the local datastore, but garbage collection may remove it at any time. See Limits and errors.

HTTP Gateway

Add file

curlpython

curl -i --data-binary @<file> https://ipfs.oversas.org/ipfs/    

import requests

headers = {
    'Content-Type': 'application/x-www-form-urlencoded',
}

with open('<file>', 'rb') as f:
    data = f.read()

response = requests.post('https://ipfs.oversas.org/ipfs/', headers=headers, data=data)

cid = response.headers['Ipfs-Hash']

Arguments:

• file [string] - The path to a file to be added to IPFS. Required: yes.

Response:

On success, the call to this endpoint will return with 201 and an empty body. The CID is returned in the response headers, not in the body:

HTTP/1.1 201 Created
Ipfs-Hash: QmbFMke1KXqnYyBBWxB74N4c5SBnJMVAiMNRcGu6x1AwQH
Location: /ipfs/QmbFMke1KXqnYyBBWxB74N4c5SBnJMVAiMNRcGu6x1AwQH

Result headers:

• Ipfs-Hash - CID of the added content.
• Location - Gateway path of the added content, /ipfs/<cid>.

Both headers are listed in the gateway's Access-Control-Expose-Headers, so they can be read from browser JavaScript on a cross-origin upload.

The added content is not pinned, whatever parameters are sent. Uploads are capped at 10 MB.

This endpoint is available on ipfs.oversas.org only. Elsewhere it returns 405.

Get content

curlwgetpython

curl https://ipfs.oversas.org/ipfs/<key>

wget https://ipfs.oversas.org/ipfs/<key>

import requests

response = requests.get('https://ipfs.oversas.org/ipfs/<key>')

Arguments:

• key [string] - The IPFS object hash. Required: yes.

Response:

On success, the call to this endpoint will return with 200 and the content itself as the body. The Content-Type is the one the gateway detects for that content, so it is not always text/plain. The X-Ipfs-Path and X-Ipfs-Roots response headers give the resolved path.

HEAD is accepted and returns the same headers without the body.

Keys beginning with bafybei or bafkrei are refused with 403 on this gateway. Other CIDv1 keys are served normally.

Get content by name

Resolve an IPNS name and serve the content it points to.

curlpython

curl -L https://ipfs.oversas.org/ipns/<name>

import requests

response = requests.get('https://ipfs.oversas.org/ipns/<name>')

Arguments:

• name [string] - An IPNS name, either a peer ID or a DNSLink domain. Required: yes.

Response:

On success, the call to this endpoint will return with 200 and the content itself as the body. A request for a bare name is answered with a 301 to /ipns/<name>/, so follow redirects (curl -L, or requests, which follows them by default).

This path is read only: only GET, HEAD and OPTIONS are accepted. A POST to /ipns/ returns 405. To add content, use Add file or Add.

RPC API

Add

/api/v0/add

Add a file or directory to IPFS.

curlpython

curl -X POST -F file=@<file> "https://ipfs.oversas.org/api/v0/add?quiet=true"

import requests

params = {
    'quiet': 'true',
}

files = {
    'file': open('<file>', 'rb'),
}

response = requests.post('https://ipfs.oversas.org/api/v0/add', params=params, files=files)

Arguments:

• file [string] - The path to a file to be added to IPFS. Required: yes.
• quiet [bool] - Write minimal output.
• quieter [bool]- Write only final hash.
• silent [bool] - Write no output.
• progress [bool] - Stream progress data.
• wrap-with-directory [bool] - Wrap files with a directory object.
• pin [bool] - Ignored on this gateway. Any client-supplied value is stripped and pin=false is applied instead, so the object is never pinned. See Limits and errors.
• see all params on ipfs docs

Response:

On success, the call to this endpoint will return with 200 and a newline-delimited JSON body. With quiet=true it is a single object:

{"Name":"file1","Hash":"QmY9cxiHqTFoWamkQVkpmmqzBrY3hCBEL2XNu3NtX74Fuu","Size":"14"}

Other output options emit several lines: read the CID from the last line carrying a Hash field. With progress=true, progress lines without a Hash are interleaved with it.

Result fields:

• Name - Name of the object.
• Hash - Hash of the uploaded object.
• Size - Integer indication size in bytes. This is the cumulative DAG size, which includes encoding overhead, so it is larger than the file itself.

The added content is not pinned. Uploads are capped at 10 MB.

There is no recursive param. If you want add directory, use:

curl -X POST -F file=@mydir/file1 -F file=@mydir/file2 "https://ipfs.oversas.org/api/v0/add?wrap-with-directory=true"

Cat

/api/v0/cat

Show IPFS object data.

curlpython

curl -X POST "https://ipfs.oversas.org/api/v0/cat?arg=<key>"

import requests

params = {
    'arg': '<key>',
}

response = requests.post('https://ipfs.oversas.org/api/v0/cat', params=params)

Arguments:

• arg [string] - The path (hash) to the IPFS object(s) to be outputted. Required: yes
• see all params on ipfs docs

Response:

On success, the call to this endpoint will return with 200 and text/plain body.

Get

/api/v0/get

Download IPFS objects.

curlpython

curl -X POST "https://ipfs.oversas.org/api/v0/get?arg=<key>&output=<value>&archive=false&compress=false&compression-level=-1"

import requests

params = {
    'arg': '<key>',
}

response = requests.post('https://ipfs.oversas.org/api/v0/get', params=params)

Arguments:

• arg [string] - The path (hash) to the IPFS object(s) to be outputted. Required: yes.
• output [string] - The path where the output should be stored.
• archive [bool] - Output a TAR archive.
• compress [bool] - Compress the output with GZIP compression.
• compression-level [int] - The level of compression (1-9). The default is -1.
• see all params on ipfs docs

Add --output <file> to save as binary or use: curl --location --request "https://ipfs.oversas.org/api/v0/cat?arg=<key>" --output <file> to save as text/plain

Response:

On success, the call to this endpoint will return with 200 and text/plain body.

Files stat

/api/v0/files/stat

Display file status.

curlpython

curl -X POST "https://ipfs.oversas.org/api/v0/files/stat?arg=<key>"

import requests

params = {
    'arg': '<key>',
}

response = requests.post('https://ipfs.oversas.org/api/v0/files/stat', params=params)

Arguments:

• arg [string] - Hash to file to stat. Required: yes.
• hash [bool] - Print only hash. Implies '--format='. Conflicts with other format options.
• size [bool] - Print only size. Implies '--format='. Conflicts with other format options.
• see all params on ipfs docs

Response:

On success, the call to this endpoint will return with 200 and application/json body:

{"Hash":"QmZ5rfRBvoQrXV3VnTS5SGQHTUygmRu2idAsqMwbEPQy4x","Size":0,"CumulativeSize":8635644,"Blocks":1,"Type":"directory"}

Name resolve

/api/v0/name/resolve

Resolve an IPNS name to the path it points to.

curlpython

curl -X POST "https://ipfs.oversas.org/api/v0/name/resolve?arg=<name>"

import requests

params = {
    'arg': '<name>',
}

response = requests.post('https://ipfs.oversas.org/api/v0/name/resolve', params=params)

Arguments:

• arg [string] - The IPNS name to resolve. Required: yes. A missing or empty arg is refused with 403 on this gateway.
• see all params on ipfs docs

Response:

On success, the call to this endpoint will return with 200 and application/json body:

{"Path":"/ipfs/QmfYLfDEwxvMK6UdzfJM76q1jdWM8CS5pg8cwpFBi2kxdi"}

Pin add

/api/v0/pin/add

Pin objects to local storage.

This route has been disabled

curlpython

curl -X POST "https://ipfs.oversas.org/api/v0/pin/add?arg=<key>"

import requests

params = {
    'arg': '<key>',
}

response = requests.post('https://ipfs.oversas.org/api/v0/pin/add', params=params)

Arguments:

• arg [string] - Path (hash) to object(s) to be pinned. Required: yes.
• recursive [bool] - Recursively pin the object linked to by the specified object(s). Default: true.
• progress [bool] - Show progress.
• see all params on ipfs docs

Response:

This route is disabled: the call returns 403 with body {"response": "EXCEPTION_403_FORBIDDEN"}.

Pin ls

/api/v0/pin/ls

List objects pinned to local storage.

This route has been disabled

curlpython

curl -X POST "https://ipfs.oversas.org/api/v0/pin/ls?arg=<key>"

import requests

params = {
    'arg': '<key>',
}

response = requests.post('https://ipfs.oversas.org/api/v0/pin/ls', params=params)

Arguments:

• arg [string] - Path (hash) to object(s) to be listed. Required: yes.
• see all params on ipfs docs

Response:

This route is disabled: the call returns 403 with body {"response": "EXCEPTION_403_FORBIDDEN"}.

Pin rm

/api/v0/pin/rm

Remove object from pin-list.

This route has been disabled

curlpython

curl -X POST "https://ipfs.oversas.org/api/v0/pin/rm?arg=<key>"

import requests

params = {
    'arg': '<key>',
}

response = requests.post('https://ipfs.oversas.org/api/v0/pin/rm', params=params)

Arguments:

• arg [string] - Path (hash) to object(s) to be unpinned. Required: yes.
• recursive [bool]: Recursively unpin the object linked to by the specified object(s). Default: true.
• see all params on ipfs docs

Response:

This route is disabled: the call returns 403 with body {"response": "EXCEPTION_403_FORBIDDEN"}.

Routing findpeer

/api/v0/routing/findpeer

Find the multiaddresses associated with a Peer ID.

curlpython

curl -X POST "https://ipfs.oversas.org/api/v0/routing/findpeer?arg=<peerID>"

import requests

params = {
    'arg': '<peerID>',
}

response = requests.post('https://ipfs.oversas.org/api/v0/routing/findpeer', params=params)

Arguments:

• arg [string]: The ID of the peer to search for. Required: yes.
• see all params on ipfs docs

Response:

On success, the call to this endpoint will return with 200 and application/json body.

Routing findprovs

/api/v0/routing/findprovs

Find peers that can provide a specific value, given a key.

curlpython

curl -X POST "https://ipfs.oversas.org/api/v0/routing/findprovs?arg=<key>"

import requests

params = {
    'arg': '<key>',
}

response = requests.post('https://ipfs.oversas.org/api/v0/routing/findprovs', params=params)

Arguments:

• arg [string]: The key (hash) to find providers for. Required: yes.
• see all params on ipfs docs

Response:

On success, the call to this endpoint will return with 200 and application/json body.

Limits and errors

Nothing is pinned

Content added through either route, the gateway POST /ipfs/ or the RPC /api/v0/add, is not pinned. The pin parameter is stripped and forced to false, so there is no way to pin through this gateway. Added content is served as long as it stays in the node's datastore, and a garbage collection can drop it at any time.

If you need the content to last, pin it on a node you control, or keep the original and add it again.

Which host accepts what

• ipfs.oversas.org is the only host that accepts writes: POST /ipfs/ and POST /api/v0/add.
• oversas.org, www.oversas.org, drive.oversas.org and docs.oversas.org expose the gateway read only. Any write there returns 405.
• PUT and DELETE are never accepted. POST /ipns/ is never accepted either.
• OPTIONS is accepted everywhere, so the CORS preflight of ranged browser requests keeps working.

Size

Both add routes are capped at 10 MB. A larger body returns 413.

Rate limits

Per client IP:

• gateway paths (/ipfs, /ipns): 10 requests per second, bursts up to 20, at most 20 concurrent connections.
• RPC paths (/api/v0/...): 2 requests per second, bursts up to 5, at most 10 concurrent connections.

Exceeding a limit returns 503.

Reachable endpoints

Only the endpoints listed on this page are routed. Any other /api/v0/... path returns 403, whether or not Kubo implements it.

Error format

On ipfs.oversas.org errors are JSON objects, for example:

{"response": "EXCEPTION_403_FORBIDDEN"}

The codes used are 400, 403, 404, 405, 413 and 500. Three cases fall back to the server's default HTML page instead: 405 and 413 raised on the gateway /ipfs path, and 503 from a rate limit. Test the status code rather than parsing the error body.

Online App

IPFS API

OpenEdit