Difference between revisions of "API Upload Project Assets"

From zFairs Contest Management
(Created page with "== Upload Project Image == You can use our api to upload images to a project, so these can be viewed by your judges or in the showcase. To do this you need to POST a message t...")
 
(Remove username/password API auth; ApiKey only)
 
(10 intermediate revisions by 4 users not shown)
Line 1: Line 1:
−
== Upload Project Image ==
+
== Upload Project Assets ==
−
You can use our api to upload images to a project, so these can be viewed by your judges or in the showcase. To do this you need to POST a message to your site. Below is an example of what needs to be posted.
+
Upload project images/assets or paperwork files to an existing project.
 +
 
 +
=== Authentication ===
 +
All data API calls are <code>POST</code> (unless noted) with JSON body:
 +
 
 +
{| class="wikitable"
 +
|-
 +
! Field !! Required !! Description
 +
|-
 +
| <code>ApiKey</code> || Yes || Private API key for your site.
 +
|-
 +
| <code>FairId</code> || Yes || Fair GUID from the site URL (<code>f</code> query parameter).
 +
|-
 +
| <code>Body</code> || Depends || Request payload. Use <code>{}</code> when no body fields are needed.
 +
|}
 +
 
 +
 
 +
Calls must be run '''server-side''' — do not expose your API key in a browser.
 +
 
 +
=== Response envelope ===
 +
Most endpoints return:
 +
 
 +
<pre>
 +
{
 +
  Success: true,
 +
  Message: null,  // error text when Success is false
 +
  Body: { ... }    // endpoint-specific payload
 +
}
 +
</pre>
 +
 
 +
 
 +
=== Upload project image / asset ===
 +
POST <code>/api/data/project/file</code>
  
 
<syntaxhighlight lang="JavaScript" line>
 
<syntaxhighlight lang="JavaScript" line>
 +
fetch('/api/data/project/file', {
 +
    method:'POST',
 +
    headers:{'Content-Type': 'application/json'},
 +
    body: JSON.stringify({
 +
            ApiKey:'<Private key>',
 +
            FairId: '9df61f13-474b-442f-ac1f-edca7348ef71',
 +
            Body: {
 +
ProjectKey: "32161f13-474b-442f-ac1f-edca7348e000",
 +
Base64String: "iVBORw0KGgoAAAANSUhEUgAAAQIAA...", // not required if DownloadFromUrl is set
 +
DownloadFromUrl: "https://yoursite.com/somefile.png", // optional alternative to Base64String
 +
FileName: "myAwesomeFile.png",
 +
Caption: "indescribable"
 +
}
 +
        })
 +
})
 +
.then(response => response.json())
 +
.then(data=>{console.log('Success: ',data);})
 +
.catch((error)=>{console.log('Error: ', error);});
 +
</syntaxhighlight>
  
−
fetch('/api/data/project', {
+
=== Upload project paperwork ===
 +
Same endpoint. Paperwork should be PDF. Set <code>PaperworkFileType</code> from [[API Get Info]] → <code>PaperworkFileTypes</code>.
 +
 
 +
<syntaxhighlight lang="JavaScript" line>
 +
fetch('/api/data/project/file', {
 
     method:'POST',
 
     method:'POST',
 
     headers:{'Content-Type': 'application/json'},
 
     headers:{'Content-Type': 'application/json'},
 
     body: JSON.stringify({
 
     body: JSON.stringify({
−
             Username:'admin username',
+
             ApiKey:'<Private key>',
−
            Password: 'password',
+
             FairId: '9df61f13-474b-442f-ac1f-edca7348ef71',
−
             FairId: '9df61f13-474b-442f-ac1f-edca7348ef71', //This value can be found in your url it's the value of f
 
 
             Body: {
 
             Body: {
−
"ProjectKey":"32161f13-474b-442f-ac1f-edca7348e000"
+
ProjectKey: "32161f13-474b-442f-ac1f-edca7348e000",
−
"Base64String" : "iVBORw0KGgoAAAANSUhEUgAAAQIAA...",
+
PaperworkFileType: 123,
−
"DownloadFromUrl":"http://yoursite.com/somefile.png" //optional can be used in stead of Base64String
+
Base64String: "JVBERi0xLjQK...",
−
"FileName": "myAwesomeFile.png",
+
DownloadFromUrl: null,
−
"Caption": "indescribable"
+
FileName: "form1c.pdf",
 +
Caption: "Form 1C"
 
}
 
}
 
         })
 
         })
Line 23: Line 78:
 
.then(data=>{console.log('Success: ',data);})
 
.then(data=>{console.log('Success: ',data);})
 
.catch((error)=>{console.log('Error: ', error);});
 
.catch((error)=>{console.log('Error: ', error);});
 +
</syntaxhighlight>
 +
 +
=== Response ===
 +
<pre>
 +
{
 +
  Success: true,
 +
  Message: null,
 +
  Body: { ProjectKey: "...", FileName: "myAwesomeFile.png", ... }
 +
}
 +
</pre>
 +
 +
If the project key is invalid:
  
−
</syntaxhighlight>
+
<pre>
 +
{ Success: false, Message: "Project not found with ProjectKey: ..." }
 +
</pre>
 +
 
 +
=== Field notes ===
 +
* Provide '''either''' <code>Base64String</code> '''or''' <code>DownloadFromUrl</code>.
 +
* When <code>PaperworkFileType</code> &gt; 0, the file is stored as paperwork; otherwise as a project asset/image.
 +
* Uploaded files appear on [[API Get Projects]] under <code>projectFiles</code> / <code>paperworkFiles</code> with a <code>/file/showfile/{publicId}</code> path.
 +
 
 +
=== Related APIs ===
 +
* [[API Get Projects]]
 +
* [[API Get Info]]
 +
* [[API Add Project]] / [[API Update Project]]
 +
 
 +
<br/><br/>
 +
[[Category: API]]

Latest revision as of 12:55, 25 July 2026

Upload Project Assets

Upload project images/assets or paperwork files to an existing project.

Authentication

All data API calls are POST (unless noted) with JSON body:

Field Required Description
ApiKey Yes Private API key for your site.
FairId Yes Fair GUID from the site URL (f query parameter).
Body Depends Request payload. Use {} when no body fields are needed.


Calls must be run server-side — do not expose your API key in a browser.

Response envelope

Most endpoints return: 

{
  Success: true,
  Message: null,   // error text when Success is false
  Body: { ... }    // endpoint-specific payload
}


Upload project image / asset

POST /api/data/project/file 

fetch('/api/data/project/file', {
    method:'POST',
    headers:{'Content-Type': 'application/json'},
    body: JSON.stringify({
            ApiKey:'<Private key>',
            FairId: '9df61f13-474b-442f-ac1f-edca7348ef71',
            Body: {
				ProjectKey: "32161f13-474b-442f-ac1f-edca7348e000",
				Base64String: "iVBORw0KGgoAAAANSUhEUgAAAQIAA...", // not required if DownloadFromUrl is set
				DownloadFromUrl: "https://yoursite.com/somefile.png", // optional alternative to Base64String
				FileName: "myAwesomeFile.png",
				Caption: "indescribable"
			}
        })
})
.then(response => response.json())
.then(data=>{console.log('Success: ',data);})
.catch((error)=>{console.log('Error: ', error);});

Upload project paperwork

Same endpoint. Paperwork should be PDF. Set PaperworkFileType from API Get Info → PaperworkFileTypes. 

fetch('/api/data/project/file', {
    method:'POST',
    headers:{'Content-Type': 'application/json'},
    body: JSON.stringify({
            ApiKey:'<Private key>',
            FairId: '9df61f13-474b-442f-ac1f-edca7348ef71',
            Body: {
				ProjectKey: "32161f13-474b-442f-ac1f-edca7348e000",
				PaperworkFileType: 123,
				Base64String: "JVBERi0xLjQK...",
				DownloadFromUrl: null,
				FileName: "form1c.pdf",
				Caption: "Form 1C"
			}
        })
})
.then(response => response.json())
.then(data=>{console.log('Success: ',data);})
.catch((error)=>{console.log('Error: ', error);});

Response

{
  Success: true,
  Message: null,
  Body: { ProjectKey: "...", FileName: "myAwesomeFile.png", ... }
}

If the project key is invalid: 

{ Success: false, Message: "Project not found with ProjectKey: ..." }

Field notes

  • Provide either Base64String or DownloadFromUrl.
  • When PaperworkFileType > 0, the file is stored as paperwork; otherwise as a project asset/image.
  • Uploaded files appear on API Get Projects under projectFiles / paperworkFiles with a /file/showfile/{publicId} path.

Related APIs



Retrieved from "https://wiki.zFairs.com/index.php?title=API_Upload_Project_Assets&oldid=970"