Our API uses JSON for data exchange and provides a secure, efficient solution for sharing files and content. Designed for seamless integration and built with industry-standard encryption, it ensures reliable and protected data transfers while minimizing complexity.

Authentication

API access is secured through header validation. For business services, you will be provided with two essential credentials:  x-domain  x-api-key
These credentials must be included in the headers of all API requests.

1. Creating a Link

You can create a link by sending a JSON payload to the appropriate API endpoint. The payload should include the text content, an optional password for access, an expiry time (in seconds), and optionally, a file attachment.

Payload:

content (string)
The main text content, provided in plain text (limited to 100KB).
password (string, optional)
A password for securing access to the hosted content.
expiry (integer)
The duration (in seconds) for which the content will be available (5 - 604800 seconds).
file (object, optional)
You can attach a file, which must be base64-encoded. The file must not exceed 3MB and should be in one of the supported formats: .pdf .doc .docx .png .jpg .jpeg .csv .xlsx .html

Endpoint: /new
Method: POST

Example using cURL

curl -X POST "https://api.secretonce.com/new" \
     -H "x-domain: secret.yourdomain.com" \
     -H "x-api-key: your-api-key-here" \
     -H "Content-Type: application/json" \
     -d '{
           "content": "Example content to share",
           "password": "",
           "expiry": 3600,
           "file": {
               "name": "example.png",
               "body": "iVBORw0KG..."
           }
         }'

$apiUrl = 'https://api.secretonce.com/new';
$apiDomain = 'secret.yourdomain.com';
$apiKey = 'your-api-key-here';

$data = [
    "content" => "Example content to share",
    "password" => "",
    "expiry" => 3600,
    "file" => [
        "name" => "example.png",
        "body" => base64_encode("File content")
    ]
];

$jsonData = json_encode($data);

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $apiUrl);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, $jsonData);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'x-domain: ' . $apiDomain,
    'x-api-key: ' . $apiKey,
    'Content-Type: application/json'
]);

$response = curl_exec($ch);
$status_code = curl_getinfo($ch, CURLINFO_HTTP_CODE);

    if ($status_code == 200) {
        echo $response;  // This is a JSON
    } else {
        // Handle other status codes (errors)
        echo $response;  // This is a JSON
       
    }

curl_close($ch);

Response

All successful API calls return a 200 HTTP status code in the response header, making it easy to handle responses programmatically. Unsuccessful API calls return a status code other than 200 and the body of the JSON response will contain a message field that provides detailed information to help you debug your application or log the error for further investigation. Here is an example of a successful response:

{
  "status": "success",    
  "id": "fckNe5mTEQ",    
  "url": "https://secret.yourdomain.com/?#fckNe5mTEQ", 
  "password": "no",      
  "file": "example.pdf",           
  "expiry": "2024-03-29 06:03:33"  
}

status: 'success' indicates the request was successful.
id: Unique identifier for the created link.
url: Unique URL for the created link.
password: Indicates if a password was set (yes/no).
file: The file name, if any.
expiry: Indicates when the content will be deleted (UTC).

2. Reading a Link

If your plan supports reading, you can retrieve the content from a specific endpoint by providing a valid reference in the id parameter. All successful responses will return a 200 HTTP status code in the header.

Endpoint: /read
Method: GET

Example using cURL

curl -X GET "https://api.secretonce.com/read?id=fckNe5mTEQ" \
            -H "x-domain: secret.yourdomain.com" \
            -H "x-api-key: your-api-key-here"

Response

{
  "id": "fckNe5mTEQ",
  "content": "Example content to share",
  "password": "abcde...",
  "file": {
      "name": "example.pdf",
      "body": "iVBORw0KG..."
  },
  "expiry": "2024-03-29 06:03:33"
}

id: Unique identifier for the created link.
password: The password, if set.
file: The file details, if any.
expiry: Indicates when the content will expire (UTC).

Support

Please don't hesitate to reach out to our team.