REST API‎ > ‎Media Management‎ > ‎

Request Upload Grant

This method is used to request permission to upload a file. To use this method, the application must first obtain a media ID. When successful, this method returns a grant ID that may be used to perform a single file upload. The grant ID is valid for twenty-four hours after issuance.

Method: POST
URI: /api/rest/media/{mediaid}

Path parameter:
  • mediaid  The media ID that is to be associated with the uploaded file.
Form parameters:
  • appkey  The application key
  • action  The action to be performed - ("upload_grant")
Returns:
  • CREATED(201) - The grant ID has been allocated.
  • BAD_REQUEST(400) - Missing or invalid parameter(s).
  • UNAUTHORIZED(401) - The media ID is invalid or is not associated with the application identified by the appkey parameter.
Response format: JSON

Example using curl

curl -d "appkey=1f1bbca5-b71f-4938-97b6-59fed80623bc&action=upload_grant" https://api.telesocial.com/api/rest/media/52abea0b364642dbad4769ea10763080 

Response body:

{"UploadResponse":{"message":"","status":201,"grantId":"0x3e1f2ba8bcb67848","uri":"\/api\/rest\/media\/52abea0b364642dbad4769ea10763080\/8523037174842454566"}}

Ruby Example

 def request_upload_grant(media_id)
      response = post("/api/rest/media/#{media_id}",:body => {:appkey => @api_key, :action => "upload_grant"})

      case response.status
      when 201,202
      when 400
        raise Telesocial::BadRequest.new("Missing or invalid parameter(s).", response)
      when 401
        raise Telesocial::Unauthorized.new("The media ID is invalid or is not associated with the application identified by the appkey parameter.", response)
      end

      response
    end


PHP Example

      // Check if required parameter is empty
        if (empty($mediaId)) {
            throw new TelesocialApiException(
            'Missing or invalid parameter',
            102);
        }
        // Build query
        $query = 'appkey=' . $this->APIKey . '&action=upload_grant';
        // Send query to the server
        $return = $this->sendQuery('api/rest/media/' . urlencode($mediaId),
                    $query, false
                  );
        // Small trick to cast grantid as string
        $return = preg_replace('#("grantId")\:\s*(\d+),#si', '$1:"$2",', $return);
        $return = json_decode($return);
        // Parse reply
        $return = $this->checkResponse($return, 'UploadResponse');
        // Return value based on response code
        switch ($return['status']) {
            case 201:
                return $return;
            case 400:
                throw new TelesocialApiException(
                'Missing or invalid parameter',
                102
                );
            case 401:
                return false;
        }
        return false;
    }