> ## Documentation Index
> Fetch the complete documentation index at: https://apidocs.royalti.io/llms.txt
> Use this file to discover all available pages before exploring further.
# Get File Upload URL
> Generates a pre-signed URL for uploading a file to the server with optional auto-detection.
This endpoint requires authentication. Include your Bearer token in the Authorization header.
## Description
**Auto-Detection Feature:**
* Set `autoDetect: true` to enable automatic source and period detection
* Provide `fileSample` (base64-encoded) for pre-upload analysis
* Use `autoProcessIfConfident: true` to skip manual confirmation when confidence is high
* Set `forceManualConfirmation: true` to always require manual review
**Request Payload:**
* `fileMetaData`: Required - contains uploadType, originalname, mimetype, size
* `royaltySource`: Optional if autoDetect is enabled
* `accountingPeriod`: Optional if autoDetect is enabled
* `salePeriod`: Optional sales period
* `autoDetect`: Enable automatic source/period detection (default: true)
* `fileSample`: Base64-encoded file sample for analysis
* `autoProcessIfConfident`: Auto-process if detection confidence is high
* `forceManualConfirmation`: Force manual review regardless of confidence
* `isZip`: Indicates ZIP file containing multiple files
## Code Examples
```javascript Node.js theme={null}
const response = await fetch('https://api.royalti.io/file/upload-url', {
method: 'POST',
headers: {
'Authorization': `Bearer ${token}`,
'Content-Type': 'application/json'
},
body: JSON.stringify({
"ref": "#/components/schemas/UploadUrlRequest"
})
});
const data = await response.json();
console.log(data);
```
```python Python theme={null}
import requests
response = requests.post(
'https://api.royalti.io/file/upload-url',
headers={
'Authorization': f'Bearer {token}'
},
json={"ref":"#/components/schemas/UploadUrlRequest"}
)
data = response.json()
print(data)
```
```bash cURL theme={null}
curl -X POST https://api.royalti.io/file/upload-url \
-H "Authorization: Bearer YOUR_TOKEN" \
-H "Content-Type: application/json" \
-d '{"ref":"#/components/schemas/UploadUrlRequest"}'
```
## OpenAPI
````yaml post /file/upload-url
openapi: 3.0.0
info:
title: Royalti.io API
description: "# Royalti API\r\n\r\nThis is the Royalti music royalty management platform API server.\r\n\r\n## Overview\r\n\r\nThe Royalti API provides comprehensive music royalty management services including:\r\n- Music publishing and writer management\r\n- Royalty processing and analytics\r\n- DDEX integration for music industry standards\r\n- File processing and pattern recognition\r\n- Payment processing and distribution\r\n\r\n## Authentication\r\n\r\nThe API uses JWT-based authentication with multiple protection levels:\r\n- Public endpoints for basic operations\r\n- Protected endpoints requiring valid JWT tokens\r\n- Admin endpoints for administrative functions\r\n\r\n## Features\r\n\r\n- Multi-dimensional royalty analytics\r\n- CWR (Collective Works Registration) support\r\n- DDEX integration for music metadata\r\n- Advanced file processing with pattern recognition\r\n- Real-time data processing with queue system"
version: 2.6.0
contact:
name: Royalti.io Support
email: support@royalti.io
url: https://royalti.io
license:
name: Proprietary
url: https://royalti.io/terms
servers:
- url: https://api.royalti.io
description: Production server
- url: https://api-dev.royalti.io
description: Development server
- url: http://localhost:8084
description: Local development
security:
- bearerAuth: []
tags:
- name: Accounting
description: Accounting and financial transaction operations
- name: DDEX
description: DDEX operations (ERN/MEAD, messages, delivery, providers)
- name: Label
description: Label management operations
- name: Internal Webhooks
description: Internal system webhooks for royalty processing and downloads
- name: Payment Webhooks
description: Payment processor webhook endpoints
- name: Billing Webhooks
description: Stripe billing and subscription webhooks
- name: Infrastructure Webhooks
description: Cloudflare domain and SSL webhooks
- name: Distribution Webhooks
description: Digital distribution platform webhooks (FUGA)
paths:
/file/upload-url:
post:
tags:
- File
summary: Get File Upload URL
description: >-
Generates a pre-signed URL for uploading a file to the server with
optional auto-detection.
**Auto-Detection Feature:**
- Set `autoDetect: true` to enable automatic source and period detection
- Provide `fileSample` (base64-encoded) for pre-upload analysis
- Use `autoProcessIfConfident: true` to skip manual confirmation when
confidence is high
- Set `forceManualConfirmation: true` to always require manual review
**Request Payload:**
- `fileMetaData`: Required - contains uploadType, originalname,
mimetype, size
- `royaltySource`: Optional if autoDetect is enabled
- `accountingPeriod`: Optional if autoDetect is enabled
- `salePeriod`: Optional sales period
- `autoDetect`: Enable automatic source/period detection (default: true)
- `fileSample`: Base64-encoded file sample for analysis
- `autoProcessIfConfident`: Auto-process if detection confidence is high
- `forceManualConfirmation`: Force manual review regardless of
confidence
- `isZip`: Indicates ZIP file containing multiple files
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/UploadUrlRequest'
responses:
'200':
description: Pre-signed URL generated successfully
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
default: true
message:
type: string
data:
type: object
properties:
fileId:
type: string
format: uuid
description: ID of the created file record
signedUrl:
type: string
format: uri
description: Pre-signed URL for uploading the file
detectionSessionId:
type: string
format: uuid
description: Detection session ID (if autoDetect is enabled)
requiresConfirmation:
type: boolean
description: Whether manual confirmation will be required
estimatedConfidence:
type: object
description: >-
Estimated detection confidence (if fileSample
provided)
properties:
source:
type: number
period:
type: number
schema:
type: number
example:
success: true
message: >-
File upload record created, please utilise the signedUrl to
upload the file
data:
fileId: file-uuid-123
signedUrl: https://storage.googleapis.com/royalti-uploads/...
detectionSessionId: session-uuid-456
requiresConfirmation: true
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'500':
$ref: '#/components/responses/InternalServerError'
security:
- bearerAuth: []
components:
schemas:
UploadUrlRequest:
type: object
required:
- fileMetaData
properties:
royaltySource:
type: string
description: Source of the royalty data (optional if autoDetect is true)
accountingPeriod:
type: string
format: date
description: The accounting period (YYYY-MM-DD) (optional if autoDetect is true)
salePeriod:
type: string
format: date
description: The sales period (YYYY-MM-DD)
fileMetaData:
type: object
required:
- originalname
- mimetype
properties:
uploadType:
type: string
enum:
- royalty
- invoice
- receipt
- report
description: Type of upload
default: royalty
originalname:
type: string
description: Original filename
mimetype:
type: string
description: MIME type of the file
size:
type: integer
description: File size in bytes
autoDetect:
type: boolean
description: >-
Enable automatic detection of royalty source and period from file
content
default: true
fileSample:
type: string
description: >-
Base64-encoded sample of file content for pre-upload analysis
(optional)
autoProcessIfConfident:
type: boolean
description: Automatically process file if detection confidence meets thresholds
default: false
forceManualConfirmation:
type: boolean
description: Force manual confirmation even if auto-detection confidence is high
default: false
isZip:
type: boolean
description: >-
Indicates if the file is a ZIP archive containing multiple royalty
files
default: false
responses:
BadRequest:
description: Bad request
content:
application/json:
schema:
type: object
properties:
status:
type: string
example: error
message:
type: string
example: Invalid request parameters
Unauthorized:
description: Unauthorized
content:
application/json:
schema:
type: object
properties:
status:
type: string
example: error
message:
type: string
example: Unauthorized
InternalServerError:
description: Internal server error
content:
application/json:
schema:
type: object
properties:
status:
type: string
example: error
message:
type: string
example: Internal server error
securitySchemes:
bearerAuth:
type: http
scheme: bearer
bearerFormat: JWT
description: >-
JWT Authorization header using the Bearer scheme. Format: "Bearer
{token}"
````