Difference between revisions of "API Upload Project Assets"

From zFairs Contest Management
(Remove username/password API auth; ApiKey only)
 
(One intermediate revision by the same user not shown)
Line 1: Line 1:
−
== Upload Project Assets ==  
+
== Upload Project Assets ==
 +
Upload project images/assets or paperwork files to an existing project.
  
−
=== Upload Project Image ===
+
=== Authentication ===
−
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.
+
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', {
 
fetch('/api/data/project/file', {
 
     method:'POST',
 
     method:'POST',
Line 11: Line 40:
 
     body: JSON.stringify({
 
     body: JSON.stringify({
 
             ApiKey:'<Private key>',
 
             ApiKey:'<Private key>',
−
             FairId: '9df61f13-474b-442f-ac1f-edca7348ef71', //This value can be found in your url it's the value of f
+
             FairId: '9df61f13-474b-442f-ac1f-edca7348ef71',
 
             Body: {
 
             Body: {
−
"ProjectKey":"32161f13-474b-442f-ac1f-edca7348e000",
+
ProjectKey: "32161f13-474b-442f-ac1f-edca7348e000",
−
"Base64String" : "iVBORw0KGgoAAAANSUhEUgAAAQIAA...", //not required if you use DownloadFromUrl
+
Base64String: "iVBORw0KGgoAAAANSUhEUgAAAQIAA...", // not required if DownloadFromUrl is set
−
"DownloadFromUrl":"http://yoursite.com/somefile.png", //optional can be used in stead of Base64String
+
DownloadFromUrl: "https://yoursite.com/somefile.png", // optional alternative to Base64String
−
"FileName": "myAwesomeFile.png",
+
FileName: "myAwesomeFile.png",
−
"Caption": "indescribable"
+
Caption: "indescribable"
 
}
 
}
 
         })
 
         })
Line 24: Line 53:
 
.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>
 
</syntaxhighlight>
  
−
=== Upload Project Paperwork  ===  
+
=== Upload project paperwork ===
−
You can use our API to upload project paperwork, so these can be viewed by your judges, SRC, and IRB. These files need to be PDFs. You will need to get the PaperworkFileType form the [[API Get Info]]. To do this, you need to POST a message to your site. Below is an example of what needs to be posted.
+
Same endpoint. Paperwork should be PDF. Set <code>PaperworkFileType</code> from [[API Get Info]] → <code>PaperworkFileTypes</code>.
  
 
<syntaxhighlight lang="JavaScript" line>
 
<syntaxhighlight lang="JavaScript" line>
−
 
 
fetch('/api/data/project/file', {
 
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",
−
"PaperworkFileType": 123, // this is pulled from the get info api
+
PaperworkFileType: 123,
−
"Base64String" : "iVBORw0KGgoAAAANSUhEUgAAAQIAA...", //not required if you use DownloadFromUrl
+
Base64String: "JVBERi0xLjQK...",
−
"DownloadFromUrl":"http://yoursite.com/somefile.png", //optional can be used in stead of Base64String
+
DownloadFromUrl: null,
−
"FileName": "myAwesomeFile.png"
+
FileName: "form1c.pdf",
 +
Caption: "Form 1C"
 
}
 
}
 
         })
 
         })
Line 51: 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>
  
−
</syntaxhighlight>
+
=== Response ===
 +
<pre>
 +
{
 +
  Success: true,
 +
  Message: null,
 +
  Body: { ProjectKey: "...", FileName: "myAwesomeFile.png", ... }
 +
}
 +
</pre>
 +
 
 +
If the project key is invalid:
 +
 
 +
<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/><br/><br/>
+
<br/><br/>
 
[[Category: API]]
 
[[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"